Wave Mcp

Wave Accounting MCP Server

A Model Context Protocol (MCP) server that integrates Claude with Wave Accounting to automate expense tracking and income transaction creation.

Features

• 📸 Expense Creation from Receipts: Automatically extract and create expenses from receipt text
• 💰 Income Transaction Creation: Create income transactions from payment data
• 🏢 Multi-Business Support: Manage multiple Wave businesses seamlessly
• 🔍 Vendor & Customer Search: Find existing vendors and customers
• 📊 Account Management: List and categorize transactions with proper accounts
• 🔄 Real-time Integration: Direct connection to Wave's GraphQL API

Prerequisites

• Python 3.8 or higher
• Wave Business account with API access
• Claude Desktop application
• Wave OAuth2 access token

Installation

1. Clone the repository:

git clone https://github.com/vinnividivicci/wave_mcp.git
cd wave_mcp

1. Install dependencies:

pip install -r requirements.txt

1. Create a .env file:

WAVE_ACCESS_TOKEN=your_wave_oauth2_access_token_here

Getting Your Wave Access Token

1. Follow this guide: https://developer.waveapps.com/hc/en-us/articles/360020948171-Create-a-Wave-Account-and-Test-Businesses#application

> Note: Wave API access may require approval. Check Wave's current developer program status.

Configuration

Claude Desktop Setup

Add the server to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wave-accounting": {
      "command": "python",
      "args": ["/absolute/path/to/wave_mcp/mcp_server.py"],
      "env": {
        "WAVE_ACCESS_TOKEN": "your_wave_oauth2_access_token_here"
      }
    }
  }
}

Restart Claude Desktop after saving the configuration.

Usage Examples

Creating an Expense from a Receipt

I have a receipt from Office Depot for $45.99 dated March 15, 2024. 
It's for office supplies - printer paper and pens.

Creating Income from Payment

Received payment of $1,500 from ABC Company on March 20, 2024 
for consulting services invoice #1234.

Listing Available Accounts

Show me my expense accounts in Wave.

Setting Active Business (Multi-Business Accounts)

List my Wave businesses and set the active one.

Available MCP Tools

Expense Management

• create_expense_from_receipt: Create expenses from receipt text
• search_vendor: Search for existing vendors
• get_expense_accounts: List available expense accounts

Income Management

• create_income_from_payment: Create income transactions
• search_customer: Search for existing customers
• get_income_accounts: List available income accounts

Business Management

• set_business: Set the active business
• list_businesses: List all available businesses

Debugging

• debug_accounts: List all accounts with types and subtypes for troubleshooting

Important Notes

Vendor and Customer Management

• Vendors and customers must be created manually in Wave's web interface
• The API supports searching existing vendors/customers but not creating new ones
• Transactions can be created without vendors/customers and linked later

Limitations

• Wave API doesn't support attaching receipt images/PDFs
• Maximum 2 simultaneous API requests (Wave rate limiting)
• OAuth2 tokens may expire and need refreshing

Development

Running Tests

# Currently no test suite - testing via Claude Desktop integration
python mcp_server.py

Project Structure

wave_mcp/
├── mcp_server.py          # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── README.md             # This file
├── LICENSE               # MIT License
├── CLAUDE.md             # Claude-specific instructions
├── .env                  # Your API credentials (not tracked)
└── docs/
    └── wave_api_reference.md  # Wave API documentation

Troubleshooting

"Wave client not initialized"

• Verify your WAVE_ACCESS_TOKEN is set correctly
• Check that the token has valid permissions

"No business selected"

• Use the list_businesses tool to see available businesses
• Set the active business with set_business

MCP Server Not Available in Claude

• Ensure the path in claude_desktop_config.json is absolute
• Verify Python and all dependencies are installed
• Restart Claude Desktop

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Acknowledgments

• Built for use with Claude Desktop
• Integrates with Wave Accounting
• Uses the Model Context Protocol

Security

• Never commit your .env file or API keys
• Use environment variables for all sensitive data
• Regularly rotate your API tokens
• Follow Wave's security best practices

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vinnividivicci
• Source: vinnividivicci/wave_mcp
• License: MIT

Install and usage instructions live in the source repository linked above.