Wave MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Wave MCP Server list all unpaid invoices from last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Wave MCP Server
A complete Model Context Protocol (MCP) server for Wave Accounting, providing comprehensive access to invoicing, customers, products, transactions, bills, estimates, taxes, and financial reporting.
Features
π§ 45+ Tools across 10 categories:
Invoices (10 tools)
List, get, create, update, delete invoices
Send invoices via email
Approve and mark invoices as sent
List and record invoice payments
Customers (6 tools)
List, get, create, update, delete customers
Search customers by name or email
Products (5 tools)
List, get, create, update, archive products and services
Filter by sold/bought status
Accounts (4 tools)
List, get, create, update chart of accounts
Filter by account type (ASSET, LIABILITY, EQUITY, INCOME, EXPENSE)
Transactions (6 tools)
List, get, create, update transactions
Categorize transactions to accounts
List transaction attachments
Bills (7 tools)
List, get, create, update bills (accounts payable)
List and record bill payments
Estimates (6 tools)
List, get, create, update, send estimates
Convert estimates to invoices
Taxes (3 tools)
List, get, create sales taxes
Businesses (3 tools)
List businesses
Get current or specific business details
Reporting (5 tools)
Profit & Loss (Income Statement)
Balance Sheet
Aged Receivables (A/R Aging)
Tax Summary
Cashflow Statement
π± 17 MCP Apps - Pre-built UI workflows:
invoice-dashboard - Overview of invoices with status breakdown
invoice-detail - Detailed invoice view with payments and actions
invoice-builder - Create/edit invoices with line items
customer-detail - Customer profile with invoice history
customer-grid - Searchable customer grid
product-catalog - Product/service management
chart-of-accounts - Account tree view
transaction-feed - Real-time transaction stream
transaction-categorizer - Bulk transaction categorization
bill-manager - Track and pay bills
estimate-builder - Create and manage quotes
tax-overview - Tax configuration and summary
profit-loss - P&L report with visualization
balance-sheet - Balance sheet report
cashflow-chart - Cashflow waterfall chart
aging-report - Aged receivables report
business-overview - Business dashboard with quick actions
Related MCP server: waveapps-mcp
Installation
cd servers/wave
npm install
npm run buildConfiguration
Prerequisites
Wave Account: You need a Wave account at waveapps.com
API Access Token: Get an OAuth2 access token from Wave Developer Portal
Environment Variables
# Required
WAVE_ACCESS_TOKEN=your_oauth2_access_token
# Optional - set a default business ID
WAVE_BUSINESS_ID=your_business_idUsage
As MCP Server
Run the server:
WAVE_ACCESS_TOKEN=your_token npm run devWith Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"wave": {
"command": "node",
"args": ["/path/to/mcpengine-repo/servers/wave/build/main.js"],
"env": {
"WAVE_ACCESS_TOKEN": "your_access_token",
"WAVE_BUSINESS_ID": "optional_business_id"
}
}
}
}With NPX
npx @mcpengine/wave-serverTool Examples
List Invoices
// List all invoices
wave_list_invoices({ businessId: "business_123" })
// Filter by status
wave_list_invoices({
businessId: "business_123",
status: "OVERDUE"
})
// Filter by customer
wave_list_invoices({
businessId: "business_123",
customerId: "customer_456"
})Create Invoice
wave_create_invoice({
businessId: "business_123",
customerId: "customer_456",
invoiceDate: "2025-01-15",
dueDate: "2025-02-15",
title: "January Services",
items: [
{
description: "Consulting Services",
quantity: 10,
unitPrice: "150.00",
taxIds: ["tax_789"]
},
{
productId: "product_101",
description: "Software License",
quantity: 1,
unitPrice: "500.00"
}
]
})Create Customer
wave_create_customer({
businessId: "business_123",
name: "Acme Corporation",
email: "billing@acme.com",
addressLine1: "123 Main Street",
city: "San Francisco",
provinceCode: "CA",
countryCode: "US",
postalCode: "94105"
})Generate Reports
// Profit & Loss
wave_profit_and_loss({
businessId: "business_123",
startDate: "2025-01-01",
endDate: "2025-01-31"
})
// Balance Sheet
wave_balance_sheet({
businessId: "business_123",
asOfDate: "2025-01-31"
})
// Aged Receivables
wave_aged_receivables({
businessId: "business_123",
asOfDate: "2025-01-31"
})API Architecture
GraphQL-Based
Wave uses a GraphQL API, not REST. The server handles:
Authentication: OAuth2 Bearer token
Error Handling: GraphQL error parsing and network error detection
Type Safety: Full TypeScript types for all Wave entities
Pagination: Automatic page handling for large result sets
Client Implementation
// client.ts
import { GraphQLClient } from 'graphql-request';
const client = new GraphQLClient('https://gql.waveapps.com/graphql/public', {
headers: {
Authorization: `Bearer ${accessToken}`
}
});Tool Organization
src/tools/
βββ invoices-tools.ts # 10 tools for invoice management
βββ customers-tools.ts # 6 tools for customer management
βββ products-tools.ts # 5 tools for product/service catalog
βββ accounts-tools.ts # 4 tools for chart of accounts
βββ transactions-tools.ts # 6 tools for transaction management
βββ bills-tools.ts # 7 tools for bills payable
βββ estimates-tools.ts # 6 tools for estimates/quotes
βββ taxes-tools.ts # 3 tools for sales tax management
βββ businesses-tools.ts # 3 tools for business info
βββ reporting-tools.ts # 5 tools for financial reportsType System
Complete TypeScript types for all Wave entities:
// types/index.ts
export interface Invoice {
id: string;
invoiceNumber: string;
customer: Customer;
status: 'DRAFT' | 'SENT' | 'VIEWED' | 'PAID' | 'PARTIAL' | 'OVERDUE' | 'APPROVED';
items: InvoiceItem[];
total: Money;
amountDue: Money;
amountPaid: Money;
// ... full type definitions
}Error Handling
The server provides comprehensive error handling:
try {
const invoice = await wave_get_invoice({ invoiceId: "inv_123" });
} catch (error) {
// GraphQL errors
if (error.graphQLErrors) {
console.error('GraphQL errors:', error.graphQLErrors);
}
// Network errors
if (error.networkError) {
console.error('Network error:', error.networkError);
}
// HTTP status codes
if (error.statusCode) {
console.error('HTTP status:', error.statusCode);
}
}MCP Apps
Apps are accessed via resources:
// List all apps
const apps = await readResource({ uri: "wave://apps" });
// Load specific app
const invoiceDashboard = await readResource({
uri: "wave://apps/invoice-dashboard"
});Each app includes:
Display name and description
Default tools to load
Layout configuration for UI rendering
Workflow steps (for process-driven apps)
Development
Build
npm run buildWatch Mode
npm run watchType Checking
npx tsc --noEmitLicense
MIT
Links
Contributing
Contributions welcome! Please see the main MCPEngine repository for guidelines.
Support
For issues or questions:
Wave API issues: Wave Developer Support
MCP Server issues: GitHub Issues
Available Tools
54 toolswave_aged_receivablesB
Generate an Aged Receivables (A/R Aging) report
Inputs: asOfDate, businessId.
wave_approve_invoiceC
Approve a draft invoice
Inputs: invoiceId (required), businessId.
wave_balance_sheetB
Generate a Balance Sheet report
Inputs: asOfDate (required), businessId.
wave_cashflowC
Generate a cashflow statement for a date range
Inputs: endDate (required), startDate (required), businessId.
wave_categorize_transactionC
Categorize/recategorize a transaction to a different account
Inputs: accountId (required), transactionId (required), businessId.
wave_convert_estimate_to_invoiceB
Convert an approved estimate into an invoice
Inputs: estimateId (required), dueDate, businessId, invoiceDate.
wave_create_accountA
Create a new account in the chart of accounts
Inputs: name (required), type (required), subtype, currency, +2 more.
wave_create_billC
Create a new bill
Inputs: items (required), billDate (required), vendorId (required), memo, +3 more.
wave_create_bill_paymentB
Record a payment made for a bill
Inputs: date (required), amount (required), billId (required), source, +1 more.
wave_create_customerC
Create a new customer
Inputs: name (required), city, email, currency, +8 more.
wave_create_estimateB
Create a new estimate (quote)
Inputs: items (required), customerId (required), estimateDate (required), memo, +5 more.
wave_create_invoiceC
Create a new invoice
Inputs: items (required), customerId (required), invoiceDate (required), memo, +5 more.
wave_create_invoice_paymentC
Record a payment received for an invoice
Inputs: date (required), amount (required), invoiceId (required), source, +1 more.
wave_create_productC
Create a new product or service
Inputs: name (required), isSold, isBought, unitPrice, +3 more.
wave_create_taxB
Create a new sales tax
Inputs: name (required), rate (required), businessId, description, +1 more.
wave_create_transactionC
Create a new transaction
Inputs: date (required), amount (required), accountId (required), description (required), +1 more.
wave_delete_customerA
Delete a customer (only if they have no invoices)
Inputs: customerId (required), businessId.
wave_delete_invoiceA
Delete an invoice (must be in DRAFT status)
Inputs: invoiceId (required), businessId.
wave_delete_productB
Delete (archive) a product or service
Inputs: productId (required), businessId.
wave_get_accountA
Get detailed information about a specific account
Inputs: accountId (required), businessId.
wave_get_billC
Get detailed information about a specific bill
Inputs: billId (required), businessId.
wave_get_businessA
Get detailed information about a specific business
Inputs: businessId (required).
wave_get_current_businessA
Get the currently active business (if businessId is set globally)
Inputs: no named parameters.
wave_get_customerA
Get detailed information about a specific customer
Inputs: customerId (required), businessId.
wave_get_estimateB
Get detailed information about a specific estimate
Inputs: estimateId (required), businessId.
wave_get_invoiceC
Get detailed information about a specific invoice
Inputs: invoiceId (required), businessId.
wave_get_productB
Get detailed information about a specific product or service
Inputs: productId (required), businessId.
wave_get_taxC
Get detailed information about a specific tax
Inputs: taxId (required), businessId.
wave_get_transactionB
Get detailed information about a specific transaction
Inputs: transactionId (required), businessId.
wave_list_accountsB
List all accounts in the chart of accounts
Inputs: page, type, pageSize, businessId, +1 more.
wave_list_bill_paymentsB
List payments made for a specific bill
Inputs: billId (required), businessId.
wave_list_billsB
List bills (accounts payable) for a business
Inputs: page, status, pageSize, vendorId, +1 more.
wave_list_businessesA
List all businesses accessible with the current access token
Inputs: no named parameters.
wave_list_customersC
List all customers for a business
Inputs: page, pageSize, businessId.
wave_list_estimatesC
List estimates (quotes) for a business
Inputs: page, status, pageSize, businessId, +1 more.
wave_list_invoice_paymentsA
List payments received for a specific invoice
Inputs: invoiceId (required), businessId.
wave_list_invoicesC
List invoices for a business with optional filtering
Inputs: page, status, pageSize, businessId, +1 more.
wave_list_productsC
List all products and services for a business
Inputs: page, isSold, isBought, pageSize, +2 more.
wave_list_taxesB
List all sales taxes configured for a business
Inputs: businessId, isArchived.
wave_list_transaction_attachmentsA
List attachments (receipts, documents) for a transaction
Inputs: transactionId (required), businessId.
wave_list_transactionsB
List transactions for a business with filtering options
Inputs: page, endDate, pageSize, accountId, +2 more.
wave_mark_invoice_sentA
Mark an invoice as sent (without actually sending email)
Inputs: invoiceId (required), businessId.
wave_profit_and_lossC
Generate a Profit & Loss (Income Statement) report
Inputs: endDate (required), startDate (required), businessId.
wave_search_customersA
Search customers by name or email
Inputs: query (required), limit, businessId.
wave_send_estimateB
Send an estimate to the customer via email
Inputs: estimateId (required), to, message, subject, +1 more.
wave_send_invoiceB
Send an invoice to the customer via email
Inputs: invoiceId (required), to, message, subject, +1 more.
wave_tax_summaryC
Generate a tax summary report for a date range
Inputs: endDate (required), startDate (required), businessId.
wave_update_accountC
Update an existing account
Inputs: accountId (required), name, businessId, description.
wave_update_billB
Update an existing bill
Inputs: billId (required), memo, dueDate, billNumber, +1 more.
wave_update_customerC
Update an existing customer
Inputs: customerId (required), city, name, email, +8 more.
wave_update_estimateC
Update an existing estimate
Inputs: estimateId (required), memo, title, footer, +3 more.
wave_update_invoiceC
Update an existing invoice
Inputs: invoiceId (required), memo, title, footer, +3 more.
wave_update_productB
Update an existing product or service
Inputs: productId (required), name, unitPrice, businessId, +2 more.
wave_update_transactionC
Update an existing transaction
Inputs: transactionId (required), date, businessId, description.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 54 tools
Each tool has a unique and descriptive name that clearly indicates its target entity and action (e.g., wave_create_invoice, wave_list_customers, wave_delete_product). There is no ambiguity between tools; an agent can easily distinguish them.
All 54 tools follow a consistent verb_noun pattern with the 'wave_' prefix (e.g., wave_create_invoice, wave_get_customer, wave_list_accounts). The naming convention is uniform, making the tool surface predictable and easy to navigate.
54 tools is on the higher end, but it is justified for a comprehensive accounting API covering multiple entities (customers, invoices, bills, products, taxes, transactions) and reports. Each tool serves a distinct purpose, and the count is appropriate for the domain.
Core CRUD and reporting operations are covered for most entities, but there are notable gaps: missing delete for bills, estimates, taxes, and transactions; no update for bill payments; and no delete for taxes. These omissions may hinder some workflows.
Maintenance
Related MCP Connectors
MCP server for Quaderno β tax-rate calculation, invoices, contacts, products, receipts & expenses.
MCP server for Codat β companies, connections, invoices, bills and financial statements.
MCP server for ABRA Flexi β accounting, contacts, stock and draft-checked invoice creation.
Free hosted MCP for invoices, estimates, clients, items and PDFs. OAuth authorization required.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThis project builds a read-only MCP server. For full read, write, update, delete, and action capabilities and a simplified setup, check out our free CData MCP Server for Wave Financial (beta): https://www.cdata.com/download/download.aspx?sku=HWZK-V&type=betaMIT
- AlicenseNot gradedqualityBmaintenanceThis MCP server enables AI assistants like Claude to perform Wave Accounting bookkeeping tasksβsuch as drafting invoices, managing customers, recording payments, and looking up financial dataβthrough natural language commands.8MIT
- AlicenseNot gradedqualityDmaintenanceComprehensive MCP server for Wave Accounting, providing 45+ tools across invoicing, customers, products, transactions, bills, estimates, taxes, and financial reporting, plus 17 pre-built UI workflows.5MIT
- FlicenseAqualityFmaintenanceMCP server for Wave accounting that provides tools for managing chart of accounts, invoices, customers, vendors, products, and reports via the Wave GraphQL API.6-