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

Related MCP server: MCP Alchemy

Prerequisites

• Python 3.8 or higher

• Wave Business account with API access

• Claude Desktop application

• Wave OAuth2 access token

Installation

1. Clone the repository:

2. Install dependencies:

3. Create a .env file:

Getting Your Wave Access Token

1. Log in to your Wave account

2. Navigate to Settings → API Access

3. Create a new OAuth2 application

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

Restart Claude Desktop after saving the configuration.

Usage Examples

Creating an Expense from a Receipt

Creating Income from Payment

Listing Available Accounts

Setting Active Business (Multi-Business Accounts)

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

Project Structure

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