wave-mcp

A small, read-only MCP server over Wave Accounting's public GraphQL API. Ask your books plain-English questions from any MCP client — "who owes me money?", "what just got paid?", "where did the money go?", "how's revenue this year?" — with a focus on accounts receivable, the signal Wave quietly exposes but most tools ignore (whether the customer ever opened the invoice), and payments received (including money still in Wave's payout pipeline, not yet in your bank).

FastMCP, env-var auth, no dependencies beyond mcp and requests.

Tools

Related MCP server: qbo-mcp

Scope & limits (deliberate)

• Read-only except one guarded write (wave_create_expense): dry-run default, explicit confirm=True to post, deterministic externalId so an identical call can't duplicate. Every other tool only queries. Money transactions can't be read back via the API, so verify writes in Wave's UI.

• Wave's public API has no money-transaction (bank-ledger) endpoint and no date-filterable P&L report. But account balances and invoice payments ARE exposed, so wave_profit_and_loss / wave_chart_of_accounts give real expense and net-income figures — as cumulative-to-date balances, not scoped to an arbitrary date range. For period-accurate P&L, Wave's own UI reports are authoritative.

• Revenue (wave_revenue) is accrual (by invoice date), excludes DRAFT/SAVED, and is the one figure here that IS date-filterable. Use it to cross-check the timing that the cumulative balances can't express.

Setup

python3 -m venv .venv && ./.venv/bin/pip install -r requirements.txt
export WAVE_FULL_ACCESS_TOKEN=...   # or via your secret manager
./.venv/bin/python server.py

Get WAVE_FULL_ACCESS_TOKEN from the Wave Developer Portal → your application → Full Access Token. Using your own account's token is free even on the Starter plan.

Register with an MCP client

Example stdio entry (Claude Code / Claude Desktop mcpServers):

{
  "wave": {
    "command": "/path/to/wave-mcp/.venv/bin/python",
    "args": ["/path/to/wave-mcp/server.py"],
    "env": { "WAVE_FULL_ACCESS_TOKEN": "your-token" }
  }
}

Prefer a secret manager over inlining the token — e.g. wrap the command with doppler run -- ... and keep WAVE_FULL_ACCESS_TOKEN in Doppler. Set WAVE_BUSINESS_NAME to pick a default business (otherwise the first non-personal business is used).

License

MIT © 2026 Noah Weir