Model Context Protocol server for Wave Accounting
npm install wave-mcp-server~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%\Claude\claude_desktop_config.json
json
{
"mcpServers": {
"wave": {
"command": "npx",
"args": ["-y", "wave-mcp-server@latest"],
"env": {
"WAVE_ACCESS_TOKEN": "your_wave_access_token_here"
}
}
}
}
`
$3
Add the following to your OpenCode MCP configuration:
`json
{
"mcpServers": {
"wave": {
"command": "npx",
"args": ["-y", "wave-mcp-server@latest"],
"env": {
"WAVE_ACCESS_TOKEN": "your_wave_access_token_here"
}
}
}
}
`
$3
Add the following to your Cursor settings (Settings > MCP):
`json
{
"mcpServers": {
"wave": {
"command": "npx",
"args": ["-y", "wave-mcp-server@latest"],
"env": {
"WAVE_ACCESS_TOKEN": "your_wave_access_token_here"
}
}
}
}
`
Or add via Cursor's MCP settings UI by creating a new MCP server with:
- Name: wave
- Command: npx
- Args: -y wave-mcp-server@latest
- Env: WAVE_ACCESS_TOKEN=your_token_here
Features
- 17 MCP Tools:
Business (2):
- list_businesses - List all available Wave businesses with pagination
- set_business - Set the active business for operations
Expenses (3):
- create_expense_from_receipt - Create expenses from receipt data
- search_vendor - Search for existing vendors
- get_expense_accounts - List expense accounts
Income (3):
- create_income_from_payment - Create income transactions
- search_customer - Search for existing customers
- get_income_accounts - List income accounts
Invoices (8):
- list_invoices - List invoices with pagination
- get_invoice - Get detailed invoice information
- create_invoice - Create new invoice
- update_invoice - Modify existing invoice
- delete_invoice - Delete an invoice
- clone_invoice - Copy an invoice
- approve_invoice - Approve draft invoice
- send_invoice - Email invoice to customers
Debug (1):
- debug_accounts - Debug tool for account issues
- 4 MCP Resources:
- wave://businesses - Business information
- wave://accounts - Chart of accounts
- wave://vendors - Vendors list
- wave://customers - Customers list
- Smart Account Matching:
- Fuzzy matching with synonyms
- Apartment/property number detection for rental accounts
- Multi-stage matching with confidence scoring
- Multi-Business Support:
- Pagination support for large datasets
- Auto-selection of single business
- Optional manual business selection
Getting a Wave Access Token
1. Log into Wave at https://waveapps.com
2. Go to Settings > Developer > API Access
3. Create a new OAuth2 application
4. Generate an access token
Manual Installation
If you prefer to install and run locally:
`bash
Clone the repository
git clone https://github.com/yourusername/wave-mcp-server.git
cd wave-mcp-server
Install dependencies
npm install
Build the project
npm run build
Run the server
npm start
`
$3
Create a .env file in the project root:
`bash
REQUIRED: Your Wave API access token (OAuth2 Bearer token)
WAVE_ACCESS_TOKEN=your_wave_access_token_here
OPTIONAL: Your Wave business ID (auto-detected if not provided)
WAVE_BUSINESS_ID=
OPTIONAL: Logging level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO
`
See .env.example for more details.
$3
For local development with Claude Desktop, use this config instead:
`json
{
"mcpServers": {
"wave": {
"command": "node",
"args": ["/absolute/path/to/wave-mcp-server/dist/server.js"],
"env": {
"WAVE_ACCESS_TOKEN": "your_token_here"
}
}
}
}
`
Available Tools
$3
- list_businesses - List all businesses with pagination support
- set_business - Set the active business context
$3
- create_expense_from_receipt - Create expenses from receipt data
- search_vendor - Find vendors by name or email
- get_expense_accounts - List available expense accounts
$3
- create_income_from_payment - Create income transactions from payment data
- search_customer - Find customers by name or email
- get_income_accounts - List available income accounts
$3
- list_invoices - List all invoices with filtering and pagination
- get_invoice - Get detailed information for a specific invoice
- create_invoice - Create a new invoice with items, discounts, etc.
- update_invoice - Modify an existing invoice
- delete_invoice - Delete an invoice
- clone_invoice - Copy an existing invoice
- approve_invoice - Approve a draft invoice (change status from DRAFT to SAVED)
- send_invoice - Send an invoice via email to customers
$3
- debug_accounts - Inspect accounts and test account matching
Resources
- wave://businesses - View all your businesses
- wave://accounts - Browse your chart of accounts
- wave://vendors - List all vendors
- wave://customers - List all customers
Project Structure
`
wave-mcp-server/
├── src/
│ ├── server.ts # Main entry point
│ ├── client/
│ │ ├── WaveClient.ts # GraphQL API client
│ │ ├── types.ts # TypeScript interfaces and Zod schemas
│ │ └── queries.ts # GraphQL query constants
│ ├── handlers/
│ │ ├── tools/
│ │ │ ├── index.ts # Tool registry
│ │ │ ├── expenseTools.ts # Expense-related tools
│ │ │ ├── incomeTools.ts # Income-related tools
│ │ │ ├── invoiceTools.ts # Invoice-related tools
│ │ │ ├── businessTools.ts # Business management tools
│ │ │ └── debugTools.ts # Debug tools
│ │ └── resources/
│ │ └── index.ts # Resource handlers
│ ├── utils/
│ │ ├── accountMatcher.ts # Smart account matching
│ │ ├── synonyms.ts # Category synonyms
│ │ └── logger.ts # Logging utility
│ └── config/
│ └── env.ts # Environment configuration
├── dist/ # Compiled JavaScript (generated by tsc)
├── .env.example # Environment variables template
├── package.json
├── tsconfig.json
└── README.md
``