Wave MCP
Summary: A Model Context Protocol server for Wave accounting that lets you read and manage books, transactions, invoices, estimates, and derived financial reports.
Get connection context, list/get businesses, and fetch reference data such as currencies, countries, provinces, account types, and subtypes.
Manage customers: list, search, get, create, update, and soft-delete.
Read vendors (Wave's API has no vendor writes).
Manage products/services: list, get, create, update, and archive.
Manage the chart of accounts: list with balances, get, create, update with sequence locking, and archive.
Manage sales taxes: list/get with rate history, create, update rates, and archive.
Manage invoices: list/filter, get with items and payments, create, update, clone, approve, mark sent, email, and delete.
Manage invoice payments: get, record, update, delete, and email receipts.
Manage estimates: list/get, create, update, clone, approve, mark sent/accepted, reset acceptance, convert to invoice, generate PDF, email, and delete; also manage estimate deposits and receipts.
Work with live transactions via Wave's unofficial web-app API: list/search with filters and cursors, summarize totals, get full details, create single or bulk transactions, edit with optimistic locking and dry runs, and delete.
Import a Wave Data Export to list ledger transactions and accounts offline, and run date-range reports from the snapshot.
List payments received (invoice payments and estimate deposits) with totals.
Run derived financial reports such as P&L, balance sheet, trial balance, cash flow, sales tax, aged receivables/payables, income by customer, sales by product, invoice summary, and customer statements.
Use a read-only GraphQL escape hatch for other public-API reads the shaped tools do not cover.
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 show my overdue invoices and total amount due"
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
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) |
| — |
Payments received |
| — |
Reports |
| — |
Anything else |
| — |
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 |
| current account balances | as of now only |
| invoices (invoiced) + invoice payments (paid) | any date range |
| invoice line items | any date range |
| tax on invoice lines (collected only) | any date range |
| invoices by status, overdue | any date range |
| open invoices, bucketed by days past due | as of today |
| 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 |
| 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 |
|
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.
Related MCP server: qbo-mcp
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 GitHubpi 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 loginA 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-mcpOther 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 loginEvery 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 setupsetup 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 loginOpen 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/callbacknode bin/wave-mcp.js auth # full scopes
node bin/wave-mcp.js auth --read-only
node bin/wave-mcp.js check # verify, list businessesauth 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 |
| auto | Default business. Otherwise the token's business, or the only non-personal one |
| off | Register only read tools |
| all | Comma list: |
|
| Where imported ledgers are stored (mode 600) |
| 60000 | Hard cap per tool result (trailing list items are dropped, with a note) |
| 5000 | Max records a report or search walks |
| 120000 | Cache for scans and reference data; any write clears it |
| 2 | Concurrent Wave requests (Wave's limits are tight) |
| 30000 / 3 | Per request |
| info |
|
| 127.0.0.1 / 8787 / /mcp | HTTP transport |
| loopback | Host/Origin allow-list for HTTP |
| — | 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 --httpOff 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 InspectorThe 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 pushA 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
Available Tools
73 toolswave_approve_estimateApprove estimateAIdempotent
Approve a draft estimate so it can be sent. Does not email it.
Inputs: estimateId (required).
wave_approve_invoiceApprove invoiceAIdempotent
Approve a draft invoice, which posts it to the books (status SAVED). Does not email it.
Inputs: invoiceId (required).
wave_archive_accountArchive accountADestructiveIdempotent
Archive an account (hide it while keeping its history). Wave refuses for system accounts and accounts with a balance. No un-archive through the API.
Inputs: id (required).
wave_archive_productArchive product or serviceADestructiveIdempotent
Archive a product/service so it can no longer be added to new invoices. Past invoices keep it. The API cannot un-archive (web app only).
Inputs: id (required).
wave_archive_sales_taxArchive sales taxADestructiveIdempotent
Archive a sales tax so it can no longer be applied. No un-archive through the API.
Inputs: id (required).
wave_clone_estimateClone estimateB
Copy an estimate into a new draft.
Inputs: estimateId (required).
wave_clone_invoiceClone invoiceA
Copy an invoice into a new draft.
Inputs: invoiceId (required).
wave_convert_estimate_to_invoiceConvert estimate to invoiceA
Create an invoice from an estimate (deposits paid carry over). Returns the new invoiceId.
Inputs: estimateId (required).
wave_create_accountCreate accountA
Add an account to the chart of accounts. The subtype decides its type (see wave_get_reference kind=account_subtypes).
Inputs: name (required), subtype (required), currency, displayId, +2 more.
wave_create_customerCreate customerC
Create a customer. Only name is required.
Inputs: name (required), fax, email, phone, +11 more.
wave_create_estimateCreate estimateB
Create a draft estimate (quote). Each line needs a product and a unitPrice. Optionally ask for a deposit. Nothing is emailed.
Inputs: items (required), customerId (required), memo, title, +27 more.
wave_create_invoiceCreate invoiceA
Create an invoice for a customer. Created as DRAFT unless status=SAVED (approved). Number, dates, title and notes default to the business's invoice settings. Taxes default per product; pass taxIds:[] for none. Nothing is emailed.
Inputs: items (required), customerId (required), memo, title, +24 more.
wave_create_productCreate product or serviceA
Create a product or service. Give it an incomeAccountId to sell it on invoices, an expenseAccountId to buy it, or both.
Inputs: name (required), unitPrice (required), businessId, description, +3 more.
wave_create_sales_taxCreate sales taxB
Create a sales tax. abbreviation must be unique in the business (max 10 characters).
Inputs: name (required), rate (required), abbreviation (required), taxNumber, +5 more.
wave_create_transactionCreate money transactionA
Record a bank/credit-card transaction and categorize it, as if entered in Wave's Transactions page. Expense paid by card: anchor {accountId: card, direction: WITHDRAWAL}, line {accountId: expense category, balance: INCREASE}. Sale deposited to bank: anchor {bank, DEPOSIT}, line {income account, INCREASE}. Split across several lines; they must total the anchor. Keep the returned id: wave_get_transaction / wave_list_transactions read it back. Use dryRun=true to validate without writing. Wave does not document de-duplication by externalId: if a call timed out, check the Wave web app before retrying.
Inputs: date (required), anchor (required), lineItems (required), description (required), +4 more.
wave_create_transactionsCreate money transactions in bulkA
Create up to 50 money transactions in one request (same shape as wave_create_transaction). Every transaction is checked first (amounts balance; debit and credit sides make sense for the accounts); nothing is sent if any fails. Wave applies the batch as one request and reports input errors by path (transactions.N...).
Inputs: transactions (required), dryRun, businessId.
wave_delete_customerDelete customerADestructiveIdempotent
Delete a customer. Wave removes it from lists, but the record stays readable by ID (wave_get_customer shows deleted: true); there is no undelete through the API.
Inputs: id (required).
wave_delete_estimateDelete estimateBDestructiveIdempotent
Permanently delete an estimate.
Inputs: estimateId (required).
wave_delete_estimate_paymentDelete estimate depositCDestructiveIdempotent
Delete a recorded estimate deposit payment.
Inputs: id (required).
wave_delete_invoiceDelete invoiceBDestructiveIdempotent
Permanently delete an invoice.
Inputs: invoiceId (required).
wave_delete_invoice_paymentDelete invoice paymentADestructiveIdempotent
Delete a recorded invoice payment; the invoice becomes unpaid by that amount.
Inputs: id (required).
wave_delete_transactionDelete transactionADestructiveIdempotent
Delete a transaction, as the web app's Delete does. Changes the books and account balances: confirm with the user first. Wave refuses for transactions that must be removed at their source (e.g. invoice payments, payroll). Uses Wave's web-app API (unofficial), which needs a web session: if it is missing or expired, the user runs node /app/bin/wave-mcp.js login in a terminal on 1c94a9392181.
Inputs: id (required), businessId, expectedSequence.
wave_generate_estimate_pdfGenerate estimate PDFBIdempotent
Generate (or regenerate) the estimate PDF and return its URL.
Inputs: estimateId (required).
wave_get_accountGet accountBRead-onlyIdempotent
One account with type, subtype, normal balance, current balance (account and business currency) and its sequence number.
Inputs: id (required), businessId.
wave_get_businessGet businessBRead-onlyIdempotent
Full details of one business: address, contact info, currency, timezone, whether Wave can email invoices for it, and invoice/estimate branding.
Inputs: businessId.
wave_get_contextGet Wave connection contextARead-onlyIdempotent
Start here. Returns the signed-in Wave user, how credentials are configured, the businesses this credential reaches, which one is the default, whether writes are enabled, and what the public API cannot do. Works without credentials and then explains how to set them up.
Inputs: no named parameters.
wave_get_customerGet customerARead-onlyIdempotent
One customer with address, shipping details, notes and outstanding/overdue amounts. Deleted customers are still returned by ID, marked deleted: true.
Inputs: id (required), businessId.
wave_get_estimateGet estimateBRead-onlyIdempotent
One estimate with items, taxes, discounts, deposit settings and payments, acceptance history and attachments.
Inputs: id (required), businessId.
wave_get_estimate_paymentGet estimate deposit paymentBRead-onlyIdempotent
One estimate deposit payment (or refund/void) with its estimate.
Inputs: id (required), businessId.
wave_get_invoiceGet invoiceCRead-onlyIdempotent
One invoice with line items, taxes, discounts, payments, reminders, PDF and customer view links.
Inputs: id (required), businessId.
wave_get_invoice_paymentGet invoice paymentCRead-onlyIdempotent
One invoice payment with account, method, currency details and processor info.
Inputs: id (required), businessId.
wave_get_ledger_transactionGet ledger transactionARead-onlyIdempotent
One transaction from the imported ledger with every journal line (account, debit, credit, line description, sales tax). IDs come from wave_list_ledger_transactions.
Inputs: transactionId (required), businessId.
wave_get_productGet product or serviceBRead-onlyIdempotent
One product/service with its accounts and default sales taxes.
Inputs: id (required), businessId.
wave_get_referenceGet reference dataARead-onlyIdempotent
Reference data needed to fill other tools' inputs: currencies, countries, one country with its provinces/states (kind=country, code=CA), a province by code, account types, and account subtypes (needed by wave_create_account). Lists are paginated.
Inputs: kind (required), code, page, search, +1 more.
wave_get_sales_taxGet sales taxCRead-onlyIdempotent
One sales tax with its full dated rate history.
Inputs: id (required), businessId.
wave_get_transactionGet transactionARead-onlyIdempotent
One transaction with every line: bank/card side (anchor), category lines with order numbers, amounts, sales tax, vendor/customer, tags, review status, its current sequence, and which fields Wave allows editing. Uses Wave's web-app API (unofficial), which needs a web session: if it is missing or expired, the user runs node /app/bin/wave-mcp.js login in a terminal on 1c94a9392181.
Inputs: id (required), businessId.
wave_get_vendorGet vendorCRead-onlyIdempotent
One vendor with address and contact details.
Inputs: id (required), businessId.
wave_graphql_queryRun a read-only GraphQL queryARead-onlyIdempotent
Escape hatch for reads the other tools do not shape the way you need: run one GraphQL query (never a mutation) against Wave's public API and get the raw data. Select only the fields you need, and always pass page/pageSize on connections. Schema: the wave://schema resource. Example: query($id: ID!){ business(id:$id){ customers(page:1,pageSize:5){ edges{ node{ id name } } } } }
Inputs: query (required), variables.
wave_import_ledgerImport transactions from a Wave Data ExportADestructiveIdempotent
Load the full transaction journal from Wave's Data Export so transactions can be listed and date-range reports run. Wave's public API cannot read transactions; this is the supported way to get them. Get the file: Wave → Settings → Data Export → Accounting (CSV) → Export; Wave emails a download link (valid 24 hours). Pass the path of the downloaded .zip (or the accounting .csv inside it) on the machine running this server. Replaces any earlier import for the business. Nothing is sent to Wave; the ledger is stored locally (mode 600).
Inputs: path (required), businessId.
wave_list_accountsList chart of accountsARead-onlyIdempotent
List the chart of accounts with current balances. Find transaction accounts with filters: bank accounts are types=[ASSET] subtypes=[CASH_AND_BANK]; credit cards subtypes=[CREDIT_CARD]; expense categories types=[EXPENSE]; income categories types=[INCOME].
Inputs: page, types, detail, search, +5 more.
wave_list_businessesList businessesARead-onlyIdempotent
List the Wave businesses this credential can access (paginated).
Inputs: page, pageSize, isArchived.
wave_list_customersList customersARead-onlyIdempotent
List customers with their outstanding and overdue balances. Filter by exact email, archive state or modification time; use search for a name substring.
Inputs: page, sort, email, detail, +6 more.
wave_list_estimatesList estimatesARead-onlyIdempotent
List estimates (quotes) with totals, deposit state and status. detail="full" adds line items, deposit payments and acceptance history (pages of at most 25).
Inputs: page, sort, detail, status, +10 more.
wave_list_invoicesList invoicesARead-onlyIdempotent
List invoices with totals, amount due and status. Filter by status, customer, invoice date range, modification time, number, currency or the estimate they came from (sourceId). detail="full" adds line items and payments (pages of at most 25).
Inputs: page, sort, detail, status, +11 more.
wave_list_ledger_accountsList ledger accountsARead-onlyIdempotent
Accounts that appear in the imported ledger, with their type, where the type came from (Wave chart of accounts or export labels) and line counts. Use the names or IDs to filter wave_list_ledger_transactions and account_transactions reports.
Inputs: page, pageSize, businessId.
wave_list_ledger_transactionsList ledger transactionsARead-onlyIdempotent
List and search transactions from an imported Data Export snapshot (wave_import_ledger). For live data use wave_list_transactions; this works offline and includes invoices, bills and journal entries: bank and card transactions, expenses, invoices, bills, payments, transfers and journal entries. Filter by date range, account (ID or name), text, customer, vendor, amount, direction or uncategorized only. Newest first by default. Each row has the amount on the bank/card account (or the journal total), the categories used, and the transaction ID for wave_get_ledger_transaction.
Inputs: page, sort, query, vendor, +11 more.
wave_list_paymentsList payments receivedARead-onlyIdempotent
List money received: invoice payments and estimate deposits, newest first, with totals. These are the only transaction records Wave's public API can read; bank/card transactions, expenses and money transactions created through the API cannot be listed. Filter by payment date range and customer.
Inputs: kind, sort, limit, offset, +4 more.
wave_list_productsList products and servicesARead-onlyIdempotent
List products/services (the items invoice and estimate lines must reference), with price, income/expense accounts and default sales taxes. Active only unless isArchived=true.
Inputs: page, sort, detail, isSold, +7 more.
wave_list_sales_taxesList sales taxesARead-onlyIdempotent
List sales taxes with current rate (as a fraction: 0.13 = 13%). detail="full" adds the dated rate history.
Inputs: page, detail, search, pageSize, +4 more.
wave_list_transactionsList transactionsARead-onlyIdempotent
List and search the business's transactions as Wave's Transactions page shows them: bank and card transactions, expenses, deposits, transfers, bill and invoice payments. Live data. Filter by date range, text in the description, bank/card account (accountId), category accounts (categoryIds) or uncategorizedOnly. Cursor pagination: pass nextCursor back as cursor. For totals (spend per category, month, vendor or account) use wave_summarize_transactions instead of paging through rows. Each row has the amount, direction, bank/card account, category (or categories when split), vendor, sales tax and review status. IDs work with wave_get_transaction, wave_update_transaction and wave_delete_transaction. Uses Wave's web-app API (unofficial), which needs a web session: if it is missing or expired, the user runs node /app/bin/wave-mcp.js login in a terminal on 1c94a9392181.
Inputs: sort, cursor, detail, search, +9 more.
wave_list_vendorsList vendorsARead-onlyIdempotent
List vendors (suppliers). Wave's API cannot create, change or delete vendors, and bills are not exposed.
Inputs: page, email, detail, search, +4 more.
wave_mark_estimate_acceptedMark estimate acceptedCIdempotent
Record that the customer accepted the estimate.
Inputs: estimateId (required).
wave_mark_estimate_sentMark estimate as sentAIdempotent
Record that an estimate was sent outside Wave (no email goes out).
Inputs: estimateId (required), sentAt, sendMethod.
wave_mark_invoice_sentMark invoice as sentAIdempotent
Record that an invoice was sent outside Wave (no email goes out).
Inputs: invoiceId (required), sentAt, sendMethod.
wave_record_estimate_depositRecord estimate depositB
Record a deposit received outside Wave against an estimate. paymentAccountId is where the money went (a CASH_AND_BANK account).
Inputs: amount (required), estimateId (required), paymentDate (required), paymentMethod (required), +2 more.
wave_record_invoice_paymentRecord invoice paymentA
Record a payment received outside Wave against an invoice (cash, cheque, bank transfer...). paymentAccountId is the account the money went into (usually types=[ASSET] subtypes=[CASH_AND_BANK]). The invoice must be approved, not a draft.
Inputs: amount (required), invoiceId (required), paymentDate (required), paymentMethod (required), +3 more.
wave_reset_estimate_acceptanceReset estimate acceptanceBIdempotent
Undo the customer's acceptance so the estimate can be changed or re-accepted.
Inputs: estimateId (required).
wave_run_reportRun a financial reportARead-onlyIdempotent
Financial reports computed by this server (Wave's API has no report endpoint). Rows are paginated with limit/offset; totals always cover every row. From the imported ledger (wave_import_ledger; any period, default year to date; balance-sheet style reports as of endDate): profit_and_loss, balance_sheet, cash_flow, trial_balance, account_balances, account_transactions/general_ledger (filter with account or accountId), sales_tax (sales and purchases), aged_payables, purchases_by_vendor. Without a ledger, profit_and_loss, balance_sheet, trial_balance and account_balances fall back to current account balances from the API (as of now only), and sales_tax to invoices. Live from invoices (invoice date range): income_by_customer, sales_by_product, invoice_summary; as of today: aged_receivables; customer_statement needs customerId. Not possible: tax_line, payroll_wage_tax, payroll_benefits_deductions.
Inputs: report (required), limit, offset, source, +10 more.
wave_send_estimateEmail estimateADestructive
Email an estimate through Wave to real recipients. Irreversible: confirm recipients first. The estimate must be approved.
Inputs: to (required), estimateId (required), message, subject, +5 more.
wave_send_estimate_acceptance_emailEmail estimate acceptance confirmationADestructive
Email the customer the confirmation that their estimate acceptance was recorded. Irreversible.
Inputs: estimateId (required).
wave_send_estimate_deposit_receiptEmail deposit receiptBDestructive
Email a receipt for an estimate deposit to real recipients. Irreversible.
Inputs: to (required), estimateId (required), estimatePaymentId (required), message, +4 more.
wave_send_invoiceEmail invoiceADestructive
Email an invoice through Wave to real recipients. Irreversible: confirm recipients first. Requires email sending enabled for the business (wave_get_business emailSendEnabled).
Inputs: to (required), invoiceId (required), message, subject, +3 more.
wave_send_invoice_payment_receiptEmail payment receiptBDestructive
Email a receipt for an invoice payment to real recipients. Irreversible.
Inputs: to (required), invoiceId (required), invoicePaymentId (required), message, +4 more.
wave_summarize_transactionsSummarize transactionsARead-onlyIdempotent
Totals over every matching transaction, grouped by category, month, vendor, customer or bank/card account: how much was spent on Marketing this year, spend per month, top vendors. Pages through Wave itself and returns only the totals, so use it instead of paging wave_list_transactions to add things up. Same filters as wave_list_transactions. Sums line amounts (which include sales tax): money-out lines (debits) are withdrawals, money-in lines (credits) are deposits; journal entries count by the same debit/credit rule. With categoryIds, only the lines in those categories count, so split transactions are not double counted. Uses Wave's web-app API (unofficial), which needs a web session: if it is missing or expired, the user runs node /app/bin/wave-mcp.js login in a terminal on 1c94a9392181.
Inputs: search, source, endDate, groupBy, +6 more.
wave_update_accountUpdate accountADestructiveIdempotent
Rename an account or change its description/number. Wave requires the account's current sequence (optimistic locking); it is read automatically when omitted. Pass null for description/displayId to clear them.
Inputs: id (required), name, sequence, displayId, +2 more.
wave_update_customerUpdate customerADestructiveIdempotent
Change fields on a customer. Only the fields you pass are changed; nested address/shipping objects replace the existing ones.
Inputs: id (required), fax, name, email, +11 more.
wave_update_estimateUpdate estimateADestructiveIdempotent
Change an estimate. Wave's patch requires customer, status, title, dates, currency and exchange rate; any you omit are copied from the current estimate. Passing items replaces every line.
Inputs: id (required), memo, items, title, +29 more.
wave_update_estimate_depositUpdate estimate depositCDestructiveIdempotent
Change a manually recorded estimate deposit.
Inputs: id (required), estimateId (required), memo, amount, +3 more.
wave_update_invoiceUpdate invoiceBDestructiveIdempotent
Change an invoice. Passing items replaces every line; omit items to keep them. Wave may refuse changes to paid invoices.
Inputs: id (required), memo, items, title, +24 more.
wave_update_invoice_paymentUpdate invoice paymentCDestructiveIdempotent
Change a manually recorded invoice payment.
Inputs: id (required), memo, amount, paymentDate, +3 more.
wave_update_productUpdate product or serviceBDestructiveIdempotent
Change a product/service. defaultSalesTaxIds replaces the whole list.
Inputs: id (required), name, unitPrice, description, +3 more.
wave_update_sales_taxUpdate sales taxADestructiveIdempotent
Change a sales tax. To change the rate, pass rates with an effective date; rates replaces the dated rate list, so include existing entries you want to keep (see wave_get_sales_tax).
Inputs: id (required), name, rates, taxNumber, +3 more.
wave_update_transactionEdit transactionADestructiveIdempotent
Edit a transaction as in the Wave web app: date, description, notes, reviewed (verified), bank/card account, total amount, category, vendor or customer, or the full set of split lines. Journal entries (journalEntry: true) have no bank side: edit their lines, keeping debits equal to credits. Single-category transactions: use categoryId / vendorId / customerId / amount / salesTax directly. Split transactions: pass lines (every line to keep, with order from wave_get_transaction; omit order to add a line; lines left out are removed). Line amounts include sales tax and must add up to the amount. Reads the transaction first and sends its current sequence, so it never overwrites a newer edit. dryRun=true shows the change without saving. Confirm with the user before changing amounts or accounts. Uses Wave's web-app API (unofficial), which needs a web session: if it is missing or expired, the user runs node /app/bin/wave-mcp.js login in a terminal on 1c94a9392181.
Inputs: id (required), date, lines, notes, +12 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 73 tools
Despite 73 tools, most have a clearly distinct resource+action target, and descriptions explicitly separate the tricky pairs: wave_list_transactions (live, web-app API) vs wave_list_ledger_transactions (offline Data Export snapshot), wave_create_transaction vs wave_create_transactions (batch of 50), and wave_send_invoice vs wave_mark_invoice_sent. A few residual overlaps remain (wave_summarize_transactions vs wave_run_report totals, wave_list_payments vs transaction listings), but the descriptions steer correctly in each case.
Every tool uses the wave_ prefix followed by a consistent snake_case verb_noun pattern (wave_list_customers, wave_create_invoice, wave_approve_estimate, wave_record_invoice_payment). Sub-resources extend the same scheme predictably (invoice_payment, estimate_deposit), and there is no mixing of camelCase or alternate verb styles.
73 tools is well past the heavy threshold, even for a broad accounting domain with eight-plus resources each needing full CRUD plus lifecycle actions. Some of the surface is genuinely duplicative (live transactions vs imported-ledger transactions, single vs batch create), so the set could be consolidated rather than exposing every operation separately.
Coverage is strong: full lifecycle for customers, products, accounts, sales taxes, invoices, estimates, payments and deposits, plus transactions, reporting and a GraphQL escape hatch. The notable gaps (no vendor create/update, bills not exposed, no un-archive/undelete) are documented and mostly upstream API limitations, so agents can work around them.
Maintenance
Related MCP Connectors
Read-only access to your business finances: invoices, customers, vendors, taxes, profitability.
Read Ambrook books: P&L, balance sheets, unpaid invoices, bills due, and transactions. Read-only.
11Connect QuickBooks Online to AI agents with secure read or write access across multiple companies.
Connect Claude or Cursor to books, invoices, bills, payroll, and sealed closes.
Related MCP Servers
- AlicenseAqualityFmaintenanceProvides complete MCP access to Wave Accounting, enabling AI assistants to manage invoices, payments, customers, and bookkeeping via natural language.3089 npmMIT
- AlicenseAqualityCmaintenanceEnables agents to operate QuickBooks Online for a bookkeeping tenant, including company profile, employee listing, salary updates, and dry-run payroll previews without submitting actual pay.6MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to query and manage self-hosted accounting data—invoices, balances, and books—through natural language, with read-only tools by default and optional scoped write operations.3027 PyPI1AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query a connected accounting platform for organisations, invoices, contacts, chart of accounts, and profit-and-loss reports, supporting bookkeeping, AR/AP, and financial reporting workflows.83 npmMIT