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

Clone the repository:

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

Install dependencies:

pip install -r requirements.txt

Create a .env file:

WAVE_ACCESS_TOKEN=your_wave_oauth2_access_token_here

Getting Your Wave Access Token

Log in to your Wave account
Navigate to Settings → API Access
Create a new OAuth2 application
Generate an OAuth2 Bearer access token with appropriate permissions

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 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

Wave Accounting