Content
# 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:
```bash
git clone https://github.com/yourusername/wave_mcp.git
cd wave_mcp
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Create a `.env` file:
```env
WAVE_ACCESS_TOKEN=your_wave_oauth2_access_token_here
```
## Getting Your Wave Access Token
1. Log in to your [Wave account](https://www.waveapps.com)
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`
```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
```bash
# 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](LICENSE) file for details.
## Acknowledgments
- Built for use with [Claude Desktop](https://claude.ai)
- Integrates with [Wave Accounting](https://www.waveapps.com)
- Uses the [Model Context Protocol](https://modelcontextprotocol.io)
## 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
