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.

🚀 Quick Start

The Wave Accounting MCP Server integrates Claude with Wave Accounting, enabling automated expense tracking and income transaction creation. Before you start, make sure you meet the prerequisites and follow the installation steps.

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

📦 Installation

1. Clone the repository:

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

2. Install dependencies:

pip install -r requirements.txt

3. Create a .env file:

WAVE_ACCESS_TOKEN=your_wave_oauth2_access_token_here

📚 Documentation

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.

⚠️ Important 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

Basic Usage

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.

Advanced Usage

The server provides a variety of MCP tools for different management needs.

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.

🔧 Technical Details

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.