@saccolabs/wave-mcp
MCP server for Wave accounting: live transactions (list, edit, delete), every public API entity, payments and financial reports, with context-safe pagination. Also a pi package (server + skill).
Package details
Install @saccolabs/wave-mcp from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@saccolabs/wave-mcp- Package
@saccolabs/wave-mcp- Version
1.1.0- Published
- Nov 8, 2026
- Downloads
- 486/mo · 486/wk
- Author
- saccoagustin
- License
- MIT
- Types
- extension, skill
- Size
- 558.5 KB
- Dependencies
- 3 dependencies · 0 peers
Pi manifest JSON
{
"skills": [
"./skills"
],
"extensions": [
"./extensions/wave.js"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
Wave MCP
A Model Context Protocol server for Wave accounting. It covers the whole public Wave GraphQL API (every query and every non-deprecated mutation), reads and edits transactions through the API Wave's own web app uses, adds payment listings and derived financial reports, and keeps responses small enough that a model can page through real books without flooding its context.
Not affiliated with Wave Financial. Writes change real books and some tools email real customers. Transaction reads and edits use Wave's unofficial web-app API, which Wave can change at any time.
What it can do
| Area | Read | Write |
|---|---|---|
| Businesses, user, reference data | context, list/get businesses, currencies, countries/provinces, account types/subtypes | — |
| Customers | list (filters + search), get | create, update, delete |
| Vendors | list (filters + search), get | Wave API has no vendor writes |
| Products & services | list, get | create, update, archive |
| Chart of accounts | list with balances, get | create, update (auto sequence), archive |
| Sales taxes | list, get with rate history | create, update rates, archive |
| Invoices | list (all Wave filters), get with items/payments | create, update, clone, approve, mark sent, email, delete |
| Invoice payments | get, list (see below) | record, update, delete, email receipt |
| Estimates | list, get with deposits/history | create, update, clone, approve, mark sent/accepted, reset acceptance, convert to invoice, PDF, email, delete |
| Estimate deposits | get, list | record, update, delete, email receipt |
| Transactions (live) | list/search (date, text, bank account, categories, uncategorized, source; cursor pages), get with every line, tax and sequence | create (public API, single or 50 in bulk); edit date, description, notes, reviewed, account, amount, category, vendor/customer, split lines, sales tax; delete. Web-app API, see Transactions |
| Transactions (snapshot) | wave_import_ledger a Data Export, then wave_list_ledger_transactions, ledger accounts and dated reports |
— |
| Payments received | wave_list_payments: invoice payments + estimate deposits by date/customer, with totals |
— |
| Reports | wave_run_report (below) |
— |
| Anything else | wave_graphql_query (read-only escape hatch) |
— |
73 tools, 3 resources (wave://guide, wave://limitations, wave://schema)
and 3 prompts (month_end_review, chase_overdue_invoices, record_expense).
Every tool, parameter and default is listed in docs/TOOLS.md,
which is generated from the server.
Reports
Wave's public API has no report endpoints, so wave_run_report derives them
and every result states its basis:
| Report | Source | Period |
|---|---|---|
profit_and_loss, balance_sheet, trial_balance, account_balances |
current account balances | as of now only |
income_by_customer |
invoices (invoiced) + invoice payments (paid) | any date range |
sales_by_product |
invoice line items | any date range |
sales_tax |
tax on invoice lines (collected only) | any date range |
invoice_summary |
invoices by status, overdue | any date range |
aged_receivables |
open invoices, bucketed by days past due | as of today |
customer_statement |
a customer's outstanding (or dated) invoices and payments | as of today / range |
Multi-currency totals are converted with each invoice's exchange rate and also reported per original currency.
Transactions (web-app API)
Wave's public API can create transactions but not read, edit or delete them.
wave_list_transactions, wave_summarize_transactions, wave_get_transaction,
wave_update_transaction and wave_delete_transaction use gql.waveapps.com/graphql/internal, the API
behind next.waveapps.com, with the same operations the web app sends. It is
unofficial: Wave can change it without notice, and it only accepts a
browser session token (see wave-mcp login below), not API tokens.
- Edits read the transaction first and send its
sequence(Wave's optimistic lock), so a change made meanwhile in the web app is never overwritten; passexpectedSequenceto pin the version you showed the user. - Fields Wave marks as not editable (bank-feed, reconciled, payment or payroll transactions) are refused before anything is sent.
- Line amounts include sales tax and must add up to the total; this is checked
locally.
salesTaxon a line recalculates tax through Wave's own calculator (omitamount), sets it, or removes it ([]). Wave recalculates taxes it computed itself when an amount changes and keeps manually set ones; the tool warns when that happens. - Delete is Wave's soft delete (the web app's Delete).
dryRunshows the exact patch without saving. - Journal entries (
journalEntry: true) have no bank side: edit their lines, withsideon new lines; debits must equal credits. - Verified live on 2026-11-08:
- Walked every transaction of two real businesses (over 1,300 in all), cursor page by cursor page. Each one came back exactly once, in order, and every bank balance rebuilt from them matched Wave's to the cent.
- Every filter agreed with the full walk.
- Edits were tested on throwaway transactions: header fields, review status, recategorize, amount, split/merge lines, journal lines, tax recalculation/manual/removal, stale sequence and delete.
Wave quirks found while testing, and how the tools handle them:
| Quirk | Handling |
|---|---|
| Wave's cursors repeat rows when sorting by creation date | Only date sorts are offered |
| A page can exceed the response cap | The tool returns fewer rows and points nextCursor at the last row it returned, so nothing is skipped |
accountId matches any line on the account, including journal entries |
Described in the tool |
| Search also matches line descriptions | Described in the tool |
| One invalid transaction in a bulk create crashes Wave's server, unnamed | Sides are checked against each account's normal balance before sending |
| Customer delete is soft: the record stays readable by ID | wave_get_customer marks it deleted: true |
What Wave's public API cannot do
Verified against live introspection (see wave://limitations):
- No transaction reads or edits (only creates). The tools above fill the gap through the web-app API; the Data Export import is the offline route.
- No native reports; account balances have no as-of date. Cash flow, general ledger, aged payables and purchases by vendor cannot be produced.
- No bills, bill payments, journal entries, receipts, payroll or bank feeds.
- Vendors are read-only; no un-archive; no attachment uploads.
- Invoice/estimate lines must reference a product.
Install
Node.js 20 or later. Agents get two things on top of the server:
- the
wave-accountingskill (skills/wave-accounting/SKILL.md), which covers first steps, sign-in, the tools and the safety rules; - the sign-in command, which the server puts into its connector
description,
wave_get_context(auth.signIn) and every auth error, with this machine's real path and host name.
pi / Phosphor: one command
pi install npm:@saccolabs/wave-mcp # from npm
pi install git:github.com/agustinsacco/wave-mcp # or straight from GitHub
pi installs the npm dependencies. The package's extension registers the
wave MCP server for every session (codemode exposure, which keeps the 73
tool schemas out of the context until a script uses them), and the skill joins
every session's skill index. Phosphor can also install it from Settings →
Skills & extensions. Until someone signs in, each new session shows:
Wave is not signed in on <host>. In a terminal there, run: node <package>/bin/wave-mcp.js login
A wave entry in mcp.json takes precedence over the package's registration.
Claude Code, Claude Desktop, Cursor: no clone needed
The package is on npm as
@saccolabs/wave-mcp.
npx downloads and runs it:
claude mcp add --scope user wave -- npx -y @saccolabs/wave-mcp
Other clients take the same command in their config:
{ "mcpServers": { "wave": { "command": "npx", "args": ["-y", "@saccolabs/wave-mcp"] } } }
Then sign in, in a terminal on the same machine:
npx -y @saccolabs/wave-mcp login
Every other command works the same way (npx -y @saccolabs/wave-mcp check,
… setup). When the server runs through npx, its sign-in messages show the
npx command too. These clients don't install the wave-accounting skill. They get the
same guide from the wave://guide resource, and the start-here tool points
to it. npx -y @saccolabs/wave-mcp setup adds the server and a copy of the
skill to Claude Code in one step.
From a clone: setup
git clone https://github.com/agustinsacco/wave-mcp && cd wave-mcp && npm install
node bin/wave-mcp.js setup
setup looks for pi and Claude Code, shows each change and asks first:
- pi:
pi install <this folder>. - Claude Code:
claude mcp add --scope user wave …, plus a link at~/.claude/skills/wave-accounting.
It then runs login and check. Re-running it skips whatever is already set
up, and --yes accepts every step without asking. For other clients (Claude
Desktop, Cursor, …) it prints the config entry to add:
{ "mcpServers": { "wave": { "command": "node", "args": ["/path/to/wave-mcp/bin/wave-mcp.js"] } } }
Clients without skills can read the same guide from the wave://guide
resource. Credentials and imported ledgers stay on the machine that runs the
server (~/.config/wave-mcp, ~/.local/share/wave-mcp), so sign in on each
machine where it runs.
Sign in
Credentials live outside the repository in
~/.config/wave-mcp/credentials.env (override with WAVE_CREDENTIALS_FILE),
mode 600. Never put them in MCP config arguments, source or chat. See
credentials.env.example.
Easiest: wave-mcp login (one paste, enables every tool).
node bin/wave-mcp.js login
- Open https://next.waveapps.com and sign in.
- DevTools (F12) → Network → type
graphqlin the filter (reload if empty). - Right-click a
gql.waveapps.comrequest (namedinternal) → Copy → Copy as cURL (bash, cmd, fetch and PowerShell copies all work). - Paste at the hidden prompt.
Only the authorization: Bearer token is kept (cookies and everything else
are discarded) and it is never printed. login asks Wave what kind of token
it is: a web session is saved as WAVE_SESSION_TOKEN (live transactions, and
the public API too when no API token is stored); a full access token pasted
the same way is saved as WAVE_ACCESS_TOKEN. A web session ends when you sign
out of Wave or it times out; tools then say to run login again. logout
forgets it. Piped input works too: wave-mcp login < request.txt.
Option A: full access token (does not expire; works without Wave Pro). In the developer portal → Manage applications → your app → Full access tokens → Create token:
WAVE_ACCESS_TOKEN=...
It reaches every business in your Wave account. Use it for personal use and development only.
Option B: OAuth 2 (auto-refreshing, scoped; needs Wave Pro on the business).
Register http://localhost:8765/callback as a redirect URI on the app, then:
WAVE_CLIENT_ID=...
WAVE_CLIENT_SECRET=...
WAVE_REDIRECT_URI=http://localhost:8765/callback
node bin/wave-mcp.js auth # full scopes
node bin/wave-mcp.js auth --read-only
node bin/wave-mcp.js check # verify, list businesses
auth prints the authorization URL. If your browser is on another machine,
approve there and paste the URL the browser was redirected to (the page itself
may not load). Tokens are written back to the credentials file.
Token lifecycle: the access token refreshes two minutes before expiry and once more if Wave rejects it. Wave rotates refresh tokens, so refreshes run under a cross-process file lock with a re-read. Several MCP processes (one per agent lane) can therefore share one file without invalidating each other. Writes are atomic (temp file, fsync, rename, chmod 600).
Configuration
| Variable | Default | Meaning |
|---|---|---|
WAVE_BUSINESS_ID |
auto | Default business. Otherwise the token's business, or the only non-personal one |
WAVE_MCP_READ_ONLY |
off | Register only read tools |
WAVE_MCP_TOOLSETS |
all | Comma list: context,customers,vendors,products,accounts,sales_taxes,invoices,estimates,payments,transactions,reports,ledger,graphql |
WAVE_MCP_DATA_DIR |
~/.local/share/wave-mcp |
Where imported ledgers are stored (mode 600) |
WAVE_MCP_MAX_RESPONSE_CHARS |
60000 | Hard cap per tool result (trailing list items are dropped, with a note) |
WAVE_MCP_SCAN_LIMIT |
5000 | Max records a report or search walks |
WAVE_MCP_CACHE_TTL_MS |
120000 | Cache for scans and reference data; any write clears it |
WAVE_MCP_MAX_CONCURRENCY |
2 | Concurrent Wave requests (Wave's limits are tight) |
WAVE_MCP_TIMEOUT_MS / WAVE_MCP_MAX_RETRIES |
30000 / 3 | Per request |
WAVE_MCP_LOG_LEVEL |
info | debug, info, warn, error, silent (stderr only) |
WAVE_MCP_HTTP_HOST / _PORT / _PATH |
127.0.0.1 / 8787 / /mcp | HTTP transport |
WAVE_MCP_ALLOWED_HOSTS |
loopback | Host/Origin allow-list for HTTP |
WAVE_MCP_HTTP_TOKEN |
— | Bearer token for HTTP (credentials file); required off loopback |
Use it
Ask things like "which invoices are overdue?", "recategorize last month's
Uber rides to Travel", "what did I sell by product this quarter?" or "split
this transaction between Meals and Office". The prompts give ready-made
versions: month_end_review (month), chase_overdue_invoices and
record_expense.
Streamable HTTP (one server for several clients)
node bin/wave-mcp.js serve --http # http://127.0.0.1:8787/mcp
WAVE_MCP_HTTP_HOST=100.x.y.z WAVE_MCP_ALLOWED_HOSTS=myhost,100.x.y.z node bin/wave-mcp.js serve --http
Off loopback the server refuses to start without WAVE_MCP_HTTP_TOKEN, and
clients send Authorization: Bearer <token>
(pi mcp add wave --url http://myhost:8787/mcp --bearer-token-env-var WAVE_MCP_HTTP_TOKEN).
Host and Origin headers are validated against DNS rebinding. GET /healthz
reports liveness.
Response design
- Pagination everywhere. Wave lists use
page/pageSize(default 20, max 100; 25 fordetail: "full"invoices/estimates). Reports and payments useoffset/limit. Every response sayshasMoreand givesnextPage/nextOffset. - Summary by default.
detail: "summary"returns key fields and clips long text;get_*tools return everything. - Compact JSON. Nulls, empty strings and empty lists are dropped, and
{code}/{value}wrappers are collapsed ("currency": "CAD"). Money is a decimal string. - A hard budget. Results above
WAVE_MCP_MAX_RESPONSE_CHARSare trimmed, never silently. - Totals cover all rows even when only a page of rows is returned.
- Errors are tool results (
isError: true) whose text names the fix: Wave'sinputErrorswith paths, missing IDs, unbalanced transactions with both figures, auth problems with the command to run.
MCP practices followed
- Official TypeScript SDK v2 (
@modelcontextprotocol/server), spec 2026-07-28, serving 2025-era clients from the same factory over stdio and Streamable HTTP. - Zod input schemas with per-field descriptions and bounds; arguments are validated before handlers run.
- Tool annotations on every tool:
readOnlyHint,destructiveHint(update/delete/archive/send),idempotentHint, andopenWorldHint(email sends). - Server
instructions, resources for the guide, schema and limitations, and user-invoked prompts. - stdout carries only JSON-RPC; logs go to stderr with secrets redacted.
- Read-only mode and toolsets for least privilege; no tool accepts or reveals credentials.
- Mutations are never retried after an ambiguous network failure (no duplicate writes); rate limits and 5xx on reads back off and retry.
Security
- Writes change real books, and
wave_send_*tools email real customers. The skill tells agents to confirm recipients and amounts first.WAVE_MCP_READ_ONLY=1registers only read tools. - Credentials live only in the mode-600 credentials file on the machine that
runs the server. They are never in MCP arguments, logs or tool results.
loginandsecrets setread them with echo off. - Agents are told never to ask for a token, cookie or curl command in the
chat, and never to run
loginthemselves. - The web-app API is unofficial and needs your browser session, so treat that token like your Wave password. Signing out of Wave ends it.
- HTTP binds to loopback unless a bearer token is set.
Development
npm test # unit + end-to-end over both transports (no network)
npm run test:contract # live: every query/mutation document and the inputs the
# write tools build are sent to Wave with an invalid
# token. Wave validates before it authenticates, so
# this proves they are accepted, with nothing read or written
npm run smoke # live, with your credentials: every read tool and report
npm run smoke -- --writes # plus a reversible create/update/delete round trip (test business!)
npm run docs # regenerate docs/TOOLS.md (a test fails when it is out of date)
npm run schema:update # detect upstream schema drift (exit 1 on breaking changes)
npm run inspect # MCP Inspector
The end-to-end tests run a fake Wave built from the real schema snapshot
(schema/wave.graphql), so every document is parsed, validated and executed
exactly as Wave would. The web-app API refuses introspection, so its tests use
a stateful fake (test/helpers/fake-internal.js) that reproduces the
behaviours observed live: sequence locking, JSON-encoded input errors, soft
delete and calculated vs manual sales tax.
Releasing
CI (.github/workflows/ci.yml) runs the tests on Node 20, 22 and 24 for every
push and pull request. When a push to master has a package.json version
that isn't on npm yet, and the tests pass, CI publishes it with provenance,
then tags v<version> and creates a GitHub release. To release:
npm version minor --no-git-tag-version # or patch / major
npm run docs # TOOLS.md records the version
git commit -am "x.y.z: what changed" && git push
A version with a hyphen, such as 1.2.0-beta.1, goes to the next dist-tag.
CI publishes through npm trusted publishing, so no npm token is stored in
GitHub. It was set up once with
npm trust github @saccolabs/wave-mcp --repo agustinsacco/wave-mcp --file ci.yml --allow-publish.
A NPM_TOKEN repository secret also works, as a fallback.
Related
questrade-mcp, a read-only MCP server for Questrade, works the same way: it installs the same way, signs in the same way, and has the same CLI and response design.
License
MIT