Wave Accounting MCP Server

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:

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