Wave Accounting

This MCP server connects Claude with Wave Accounting to automate expense tracking and income transaction creation. It enables you to create expenses from receipts, generate income entries from payments, manage multiple Wave businesses, search for vendors and customers, and organize transactions with correct accounts, all through a Model Context Protocol interface.

How to use

You interact with the Wave Accounting MCP Server through an MCP client such as Claude Desktop. Start the server locally, then issue natural language requests to perform actions like creating expenses from receipts or posting income from payments. You can switch active Wave businesses to work with different accounts, search for existing vendors or customers, and list or set active accounts for accurate categorization.

How to install

Prerequisites you need on your system are Python 3.8 or higher and a Wave Business account with API access. You also need the Claude Desktop application and a Wave OAuth2 access token.

# Step 1: Clone the MCP server repository
git clone https://github.com/yourusername/wave_mcp.git
cd wave_mcp

# Step 2: Install Python dependencies
pip install -r requirements.txt

# Step 3: Create an environment file with your Wave access token
# This token is your Wave OAuth2 access token
echo 'WAVE_ACCESS_TOKEN=your_wave_oauth2_access_token_here' > .env

Configuration and run details

Configure the MCP server to run under Claude Desktop by adding a runtime entry that points to the Python script and passes the required environment variable.

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

Usage examples

Create an expense from a receipt: describe the receipt text and let the server extract vendor, date, amount, and items to create expense records.

Create income from a payment: state the payer, amount, and related invoice to post an income transaction against the correct customer and income account.

List available accounts or set an active business to ensure transactions are categorized correctly for the right Wave company.

Getting Your Wave Access Token

You must obtain a Bearer access token with appropriate permissions. Sign in to Wave, go to Settings, then API Access, create a new OAuth2 application, and generate a token. Note that Wave’s developer program status may affect eligibility.

Available MCP Tools

Expense Management: create_expense_from_receipt, search_vendor, get_expense_accounts.

Income Management: create_income_from_payment, search_customer, get_income_accounts.

Business Management: set_business, list_businesses.

Debugging: debug_accounts.

Important notes

Vendors and customers must be created manually in Wave. The MCP can search for existing vendors/customers but cannot create new ones directly. Transactions can be created without linked vendors/customers and can be linked later.

Wave API does not support attaching receipt images or PDFs. Expect a maximum of two simultaneous API requests due to rate limits. OAuth2 tokens may expire and require refreshing.

Troubleshooting

If you see the error “Wave client not initialized,” verify that WAVE_ACCESS_TOKEN is set correctly and that the token has valid permissions.

If you see “No business selected,” list your Wave businesses and set the active one before making transactions.

If the MCP server is unavailable in Claude, ensure the path in your Claude Desktop configuration.json is absolute, verify Python and dependencies, and restart Claude Desktop.

Development

Running tests is not required for basic operation; you can start the server directly to test integration with Claude Desktop.

Available tools

create_expense_from_receipt

Create expenses automatically from receipt text by extracting vendor, date, line items, and total amount.

search_vendor

Search for existing vendors in Wave to associate with expenses.

get_expense_accounts

List available expense accounts to categorize expenses correctly.

create_income_from_payment

Create income transactions from incoming payments, linking to customers and income accounts.

search_customer

Search for existing customers in Wave to associate with income transactions.

get_income_accounts

List available income accounts for proper categorization of income.

set_business

Set the active Wave business context for multi-business management.

list_businesses

Retrieve the list of Wave businesses available to the account.

debug_accounts

List all accounts with their types and subtypes to aid troubleshooting.