moneybird-mcp
This server lets an MCP client read and search a Moneybird administration: contacts, invoices, banking, time and more, with optional write/delete toolsets when enabled.
Connect & manage access: authenticate via
connect_moneybird, check status (moneybird_connection_status), list and select administrations.Core data: list/get contacts, products, tax rates, ledger accounts, identities/profiles, custom fields, document styles, and users.
Invoicing: list/get sales invoices, estimates, recurring sales invoices, external sales invoices, subscriptions, and templates; download PDFs; look up invoices by number or reference.
Purchases & documents: list/get purchase invoices, receipts, general documents, general journal documents, and typeless documents; download attachments.
Banking: list financial accounts and mutations, retrieve mutations and payments by id, list/get purchase transactions (payment instructions).
Time & projects: list/get time entries and projects, with filters for period, state, contact/project/user.
Safety & configuration: read-only by default; write tools require
MONEYBIRD_ALLOW_WRITE, delete/send requireMONEYBIRD_ALLOW_DELETE; toolsets and HTTP/stdio transport can be configured via env/flags.
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., "@moneybird-mcp show me my latest unpaid invoices"
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.
moneybird-mcp
A Model Context Protocol server for the Moneybird accounting API.
It exposes Moneybird as a set of MCP tools, so an assistant such as Claude can look up contacts, read invoices, check bank mutations, log time and pull reports from your administration. Access is read-only until you turn writing on, only the everyday tools are registered by default (the rest of the API stays reachable through one generic tool), and the client paces its own requests to stay inside Moneybird's rate limit. It speaks stdio for local clients and Streamable HTTP for remote ones.
Quick start
Register the server with your client. For Claude Code:
claude mcp add moneybird -- npx -y moneybird-mcp serveThen ask your assistant to connect. The server starts without credentials and exposes a
connect_moneybird tool: it opens Moneybird's token page in your browser, asks for the token you
create there, verifies it, picks your administration and stores it — without leaving the
conversation.
That needs a client that supports MCP elicitation. Where it is unavailable the same setup runs in a terminal:
npx moneybird-mcp loginwhich walks you through the same steps and stores the result in
~/.config/moneybird-mcp/credentials.json.
Check that everything resolves before you rely on it:
npx moneybird-mcp statusstatus prints the enabled toolsets, the write and delete settings, where the credentials came
from, and the administrations the token can reach. It exits non-zero when it cannot reach
Moneybird.
Related MCP server: MOCO MCP Server
Authentication
Moneybird offers two ways to get a token, and this server supports both. Neither is fully
hands-off: Moneybird implements neither Dynamic Client Registration nor PKCE, so no flow exists
that skips creating a token or registering an application. That is a limitation of the Moneybird
API, not of this server. What the connect_moneybird tool does is remove every step around that
one — it opens the right page and captures the result for you.
Personal API token. You create it yourself at
https://moneybird.com/user/applications/new, tick the scopes you want, and paste it into
moneybird-mcp login. Simplest route. The scopes are fixed at creation, and Moneybird does not
currently expire these tokens — which also means one cannot be rotated automatically. Treat it like
a password.
OAuth application. You register an application in the same place, then:
export MONEYBIRD_CLIENT_ID=...
export MONEYBIRD_CLIENT_SECRET=...
npx moneybird-mcp login --oauthThe server opens Moneybird's authorization page, catches the redirect on
http://127.0.0.1:51739/callback, and exchanges the code. Moneybird matches redirect URIs exactly,
so that URI has to be registered with your application verbatim. Use --port to pick a different
one, or --oob to have Moneybird show the code in the browser instead of redirecting — useful
where no loopback listener can be opened. OAuth tokens can be revoked from Moneybird and refreshed
automatically when they carry an expiry.
To store a token without any prompting, for example in a provisioning script:
npx moneybird-mcp login --token "$MONEYBIRD_TOKEN"moneybird-mcp logout removes the stored file. For an OAuth credential it does not revoke the
authorization itself — do that in Moneybird.
See docs/authentication.md for scopes, refresh behaviour and the exact flows.
Configuration
Configuration comes from the environment; CLI flags override it.
Environment variables
Variable | Default | Purpose |
| — | Token to use, bypassing the stored credentials entirely. |
| from stored credentials | Administration used when a tool does not name one. |
| (none) | Full toolsets to add to the essential tools. Accepts |
|
|
|
|
|
|
|
|
|
|
| Bind address for the HTTP transport. |
|
| Port for the HTTP transport. |
|
|
|
| — | Shared secret callers must present in |
| — | OAuth application client id. Must be set together with the secret. |
| — | OAuth application client secret. |
| — | Public origin the |
| — | Postgres holding the |
| — | 32 bytes of hex encrypting Moneybird tokens at rest. |
| all six scopes | Comma-separated scopes to request during |
|
| Redirect URI for the OAuth flow. Must match the one registered with your application. |
| — | IANA time zone sent with date-sensitive requests, e.g. |
|
| API base URL. For testing against a stub. |
|
| Per-request timeout. |
|
| Retries after the first attempt, for 429 and 5xx responses. |
|
| Directory holding |
Commands
Command | What it does |
| Start the MCP server. This is the default when no command is given. |
| Authenticate and store credentials. |
| Remove the stored credentials. |
| Print the configuration and verify the connection. |
| List the tools the current settings expose. |
Flags
Flag | Command | Meaning |
|
| Serve over Streamable HTTP instead of stdio. |
|
| Bind address for |
|
| Port for |
|
| Path the MCP endpoint is served on. Default |
|
| Full toolsets on top of the essential tools; comma-separated or |
|
| Enable tools that create or modify data. |
|
| Enable tools that delete data. Implies |
|
| Default administration id. |
|
| Use the OAuth application flow. |
|
| Show the authorization code in the browser instead of redirecting. |
|
| Loopback port for the OAuth redirect. Default |
|
| Store a token without prompting. |
|
| Emit the tool list as JSON. |
| any | Print usage. |
| any | Print the version. |
Tools and toolsets
Every tool definition costs context on every request, so by default only the everyday tools are registered: contacts, sales invoices, estimates, purchase invoices and receipts, bank mutations, time entries, projects, products, ledger accounts and tax rates. Everything else in the API is reachable through two generic tools:
find_moneybird_endpointsearches the pinned endpoint list (spec/endpoints.json).moneybird_apicalls an endpoint from that list. Writes need--allow-write; deletes, sending, payments and bookings need--allow-deleteas well, exactly like the dedicated tools.
The dedicated tools are grouped by Moneybird's own domains (core, invoicing, purchases,
banking, time, reports, assets, tasks, webhooks). Enable a whole group when you use it
often enough to want its typed tools:
moneybird-mcp serve --toolsets reports # essentials plus every report tool
moneybird-mcp serve --toolsets all # everythingAn unknown name is an error, not a silent no-op.
The full per-tool listing is in docs/tools.md, or run moneybird-mcp tools.
Safety model
Every tool declares one of three access tiers, and the server only registers the ones the current settings permit. A tool that is not registered is invisible to the model — it cannot be called by mistake or talked into existence.
read — always registered.
write — creates or modifies data. Needs
--allow-writeorMONEYBIRD_ALLOW_WRITE=true.destroy — needs
--allow-deleteand--allow-write.--allow-deleteon its own does nothing.
Deleting is gated separately from writing because the two failure modes are not comparable. A
wrong write leaves a record you can correct; a delete, or an invoice sent to a customer, is not
something the API can take back. Enabling writes so an assistant can draft an invoice should not
also let it remove your bookkeeping. The destroy tier therefore covers both deletions and calls
that are irreversible in practice, such as sending a document to a contact.
Read-only is the default. Turn on the least you need:
claude mcp add moneybird --env MONEYBIRD_ALLOW_WRITE=true -- npx -y moneybird-mcp serveClient setup
Claude Code
claude mcp add moneybird -- npx -y moneybird-mcp serveWith write access and the typed report tools:
claude mcp add moneybird \
--env MONEYBIRD_ALLOW_WRITE=true \
--env MONEYBIRD_TOOLSETS=reports \
-- npx -y moneybird-mcp serveClaude Desktop
Add the server to claude_desktop_config.json:
{
"mcpServers": {
"moneybird": {
"command": "npx",
"args": ["-y", "moneybird-mcp", "serve"],
"env": {
"MONEYBIRD_ALLOW_WRITE": "true"
}
}
}
}The file lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and
%APPDATA%\Claude\claude_desktop_config.json on Windows. Restart the app after editing it.
Any stdio client
The server is a plain stdio MCP server. Run moneybird-mcp serve and speak JSON-RPC over stdin and
stdout. Diagnostics go to stderr, never stdout.
{
"command": "npx",
"args": ["-y", "moneybird-mcp", "serve"],
"env": {
"MONEYBIRD_API_TOKEN": "..."
}
}If you would rather not store credentials on disk, set MONEYBIRD_API_TOKEN in the client's env
block. It takes precedence over anything in credentials.json.
Docker and self-hosting
docker build -t moneybird-mcp .
docker run --rm -p 3000:3000 -e MONEYBIRD_API_TOKEN=... moneybird-mcpThe image defaults to the HTTP transport on 0.0.0.0:3000 and exposes /mcp, plus an unauthenticated
/healthz. Do not put it on a public address without authentication.
docs/hosting.md covers the three HTTP authentication modes, multi-tenant
passthrough deployments, reverse-proxy notes and connecting a remote client.
Rate limits
Moneybird allows 150 requests per 5 minutes per IP, and 50 per 5 minutes for /reports
endpoints. The client keeps its own sliding-window counters for both budgets and delays a request
that would exceed one, so ordinary use does not produce 429s. When Moneybird returns a 429 anyway,
the client honours Retry-After and otherwise backs off exponentially with full jitter, up to
MONEYBIRD_MAX_RETRIES attempts.
The budget is per IP, not per token. Several instances behind one egress address share it, and the local counters cannot see each other. Size deployments accordingly.
Development
npm install
npm run build # before typecheck: the docs generator imports the built output
npm run typecheck
npm test
npm run formatdocs/tools.md is generated from the tool definitions. Regenerate it after adding or changing a
tool:
npm run docs:toolsspec/endpoints.json pins Moneybird's published operation list, and a test checks every path a
tool calls against it. Refresh it when Moneybird ships API changes:
npm run spec:refresh
npm testA failing endpoint test after a refresh means a route a tool depends on moved or was withdrawn.
Contributing
Issues and pull requests are welcome at
https://github.com/HalloSouf/moneybird-mcp. Please run npm run typecheck, npm test and
npm run format:check before opening a pull request; CI runs the same checks on Node 20 and 22.
Licence
MIT. See LICENSE.
Available Tools
52 toolsconnect_moneybirdConnect to MoneybirdARead-onlyIdempotent
Authenticate this server against a Moneybird account. Call it when other tools report missing or rejected credentials. It opens the Moneybird token page and stores the token you create.
Inputs: token, administration_id.
download_document_attachmentDownload document attachmentARead-onlyIdempotent
Return a temporary download URL for one attachment of a document. Get the attachment ids from the document itself with get_purchase_invoice, get_receipt or the matching get tool.
Inputs: document_id (required), attachment_id (required), document_type (required), administration_id.
download_estimate_pdfDownload estimate PDFARead-onlyIdempotent
Return a download URL for the estimate PDF. The link is signed and expires after 30 seconds, so use it immediately.
Inputs: estimate_id (required), media, administration_id.
download_sales_invoice_pdfDownload sales invoice PDFARead-onlyIdempotent
Return a download URL for the invoice PDF. The link is signed and expires after 30 seconds, so use it immediately.
Inputs: sales_invoice_id (required), media, administration_id.
find_sales_invoice_by_invoice_idFind sales invoice by invoice numberARead-onlyIdempotent
Look up a sales invoice by its printed invoice number, e.g. "2025-0001". Drafts have no invoice number and are never found this way.
Inputs: invoice_id (required), administration_id.
find_sales_invoice_by_referenceFind sales invoice by referenceARead-onlyIdempotent
Look up a sales invoice by the reference you set on it, e.g. a PO or project code.
Inputs: reference (required), administration_id.
get_contactGet contactARead-onlyIdempotent
Retrieve a single contact by its Moneybird id, or by your own customer_id reference.
Inputs: contact_id, customer_id, administration_id.
get_estimateGet estimateARead-onlyIdempotent
Retrieve one estimate by its Moneybird id, or by the estimate number printed on the document (estimate_number, e.g. "2025-0001").
Inputs: estimate_id, estimate_number, administration_id.
get_external_sales_invoiceGet external sales invoiceARead-onlyIdempotent
Retrieve one external sales invoice, including its lines and payments.
Inputs: external_sales_invoice_id (required), administration_id.
get_financial_mutationGet financial mutationARead-onlyIdempotent
Retrieve one bank transaction by id, including the payments and ledger bookings currently linked to it.
Inputs: financial_mutation_id (required), administration_id.
get_general_documentGet general documentARead-onlyIdempotent
Retrieve one general document by id, with its attachments and notes.
Inputs: general_document_id (required), administration_id.
get_general_journal_documentGet general journal documentARead-onlyIdempotent
Retrieve one general journal document by id, with its debit and credit entries.
Inputs: general_journal_document_id (required), administration_id.
get_identityGet identityARead-onlyIdempotent
Retrieve one identity, or the administration default when no id is given.
Inputs: identity_id, administration_id.
get_ledger_accountGet ledger accountBRead-onlyIdempotent
Retrieve a single ledger account.
Inputs: ledger_account_id (required), administration_id.
get_paymentGet paymentARead-onlyIdempotent
Retrieve a payment by id, whichever document it belongs to. Payment ids appear on invoices, receipts and on the bookings of a financial mutation.
Inputs: payment_id (required), administration_id.
get_productGet productARead-onlyIdempotent
Retrieve a product by Moneybird id or by its identifier.
Inputs: identifier, product_id, administration_id.
get_projectGet projectARead-onlyIdempotent
Retrieve a single project by id, with its name, state and budget.
Inputs: project_id (required), administration_id.
get_purchase_invoiceGet purchase invoiceARead-onlyIdempotent
Retrieve one purchase invoice by id, with its lines, payments, attachments and notes.
Inputs: purchase_invoice_id (required), administration_id.
get_purchase_transactionGet purchase transactionARead-onlyIdempotent
Retrieve one purchase transaction by id, with its amount, state and the document it pays.
Inputs: purchase_transaction_id (required), administration_id.
get_receiptGet receiptARead-onlyIdempotent
Retrieve one receipt by id, with its lines, payments, attachments and notes.
Inputs: receipt_id (required), administration_id.
get_recurring_sales_invoiceGet recurring sales invoiceARead-onlyIdempotent
Retrieve one recurring invoice schedule, including its lines and next invoice date.
Inputs: recurring_sales_invoice_id (required), administration_id.
get_sales_invoiceGet sales invoiceARead-onlyIdempotent
Retrieve one sales invoice by its Moneybird id, including its lines, payments and notes.
Inputs: sales_invoice_id (required), administration_id.
get_subscriptionGet subscriptionARead-onlyIdempotent
Retrieve one subscription, including its product, billing cycle and recurring invoice.
Inputs: subscription_id (required), administration_id.
get_time_entryGet time entryARead-onlyIdempotent
Retrieve a single time entry by id, with its contact, project, user and billable state.
Inputs: time_entry_id (required), administration_id.
get_typeless_documentGet typeless documentARead-onlyIdempotent
Retrieve one typeless document by id, with its attachments.
Inputs: typeless_document_id (required), administration_id.
list_administrationsList administrationsARead-onlyIdempotent
List every Moneybird administration this token can access, with id, name, language, currency and country. Use this first to discover the administration id other tools need.
Inputs: no named parameters.
list_contactsList contactsARead-onlyIdempotent
List or search contacts (customers and suppliers). Supply query for free-text search across name, email, phone, customer id, tax number and address, or filter for structured narrowing.
Inputs: page, query, filter, per_page, +2 more.
list_custom_fieldsList custom fieldsARead-onlyIdempotent
List the custom fields defined for contacts, sales invoices and identities, with the ids needed to set them.
Inputs: administration_id.
list_document_stylesList document stylesARead-onlyIdempotent
List the document styles (invoice and estimate layouts) of the administration.
Inputs: administration_id.
list_estimatesList estimatesARead-onlyIdempotent
List estimates (quotes). Defaults to the current financial year, so pass an explicit period in the filter to look further back.
Inputs: page, filter, per_page, administration_id.
list_external_sales_invoicesList external sales invoicesARead-onlyIdempotent
List revenue invoiced outside Moneybird, e.g. by a webshop or POS. Defaults to the current financial year, so pass an explicit period in the filter to look further back.
Inputs: page, filter, per_page, administration_id.
list_financial_accountsList financial accountsARead-onlyIdempotent
List the bank and payment provider accounts of the administration, with the ids that financial mutations and statements reference as financial_account_id.
Inputs: administration_id.
list_financial_mutationsList financial mutationsARead-onlyIdempotent
List bank transactions. Without a filter Moneybird returns the current financial year only, so pass an explicit period to look further back.
Inputs: filter, administration_id.
list_general_documentsList general documentsARead-onlyIdempotent
List general documents: filed paperwork such as contracts and correspondence that carries a date and reference but no amounts. Narrow with filter; keys: period (named period such as this_year/prev_quarter, or a range like 20260101..20260131), state (all|new|saved|open|paid|late|pending_payment — paid, late and pending_payment only apply to purchase invoices and receipts), recurring (all|enabled|disabled), attachment (all|with|without), reference, contact_id, ledger_account_id, updated_after (ISO 8601 UTC).
Inputs: page, filter, per_page, administration_id.
list_general_journal_documentsList general journal documentsARead-onlyIdempotent
List general journal documents (manual journal entries). Narrow with filter; keys: period (named period such as this_year/prev_quarter, or a range like 20260101..20260131), state (all|new|saved|open|paid|late|pending_payment — paid, late and pending_payment only apply to purchase invoices and receipts), recurring (all|enabled|disabled), attachment (all|with|without), reference, contact_id, ledger_account_id, updated_after (ISO 8601 UTC).
Inputs: page, filter, per_page, administration_id, +1 more.
list_identitiesList identitiesARead-onlyIdempotent
List the identities (sender profiles) an administration can invoice under, including the default one.
Inputs: administration_id.
list_ledger_accountsList ledger accountsARead-onlyIdempotent
List the chart of accounts. Bookings and invoice lines reference these by ledger_account_id.
Inputs: administration_id.
list_productsList productsARead-onlyIdempotent
List the product catalogue, optionally narrowed by free-text query or currency.
Inputs: page, query, active, currency, +2 more.
list_projectsList projectsARead-onlyIdempotent
List projects. Moneybird returns only active projects unless the filter says otherwise. Time entries reference these by project_id.
Inputs: page, filter, per_page, administration_id.
list_purchase_invoicesList purchase invoicesARead-onlyIdempotent
List purchase invoices (bills received from suppliers), newest first. Narrow with filter; keys: period (named period such as this_year/prev_quarter, or a range like 20260101..20260131), state (all|new|saved|open|paid|late|pending_payment — paid, late and pending_payment only apply to purchase invoices and receipts), recurring (all|enabled|disabled), attachment (all|with|without), reference, contact_id, ledger_account_id, updated_after (ISO 8601 UTC).
Inputs: page, filter, per_page, administration_id.
list_purchase_transactionsList purchase transactionsARead-onlyIdempotent
List outgoing payment instructions (purchase transactions). Moneybird defaults to unbatched:true, so pass an explicit filter to see transactions already collected into a batch.
Inputs: page, filter, per_page, administration_id.
list_receiptsList receiptsARead-onlyIdempotent
List receipts (expenses paid on the spot, without a supplier invoice). Narrow with filter; keys: period (named period such as this_year/prev_quarter, or a range like 20260101..20260131), state (all|new|saved|open|paid|late|pending_payment — paid, late and pending_payment only apply to purchase invoices and receipts), recurring (all|enabled|disabled), attachment (all|with|without), reference, contact_id, ledger_account_id, updated_after (ISO 8601 UTC).
Inputs: page, filter, per_page, administration_id.
list_recurring_sales_invoicesList recurring sales invoicesARead-onlyIdempotent
List the recurring invoice schedules. Only active schedules are returned unless the filter says otherwise.
Inputs: page, filter, per_page, administration_id.
list_sales_invoicesList sales invoicesARead-onlyIdempotent
List sales invoices. Defaults to the current financial year, so pass an explicit period in the filter to look further back.
Inputs: page, filter, per_page, administration_id.
list_subscriptionsList subscriptionsARead-onlyIdempotent
List the subscriptions of one contact. Moneybird has no administration-wide subscription list, so contact_id is required.
Inputs: contact_id (required), administration_id.
list_subscription_templatesList subscription templatesARead-onlyIdempotent
List the subscription templates of the administration. Requires the settings scope rather than sales_invoices.
Inputs: page, per_page, administration_id.
list_tax_ratesList tax ratesARead-onlyIdempotent
List the VAT rates configured for the administration. Invoice lines reference these by tax_rate_id.
Inputs: page, filter, per_page, administration_id.
list_time_entriesList time entriesARead-onlyIdempotent
List tracked time. Without a filter Moneybird returns the current financial year, so pass an explicit period to look further back, and include_active:true to see timers that are still running.
Inputs: page, query, filter, per_page, +1 more.
list_typeless_documentsList typeless documentsARead-onlyIdempotent
List typeless documents: uploads parked in Moneybird that have not been classified as an invoice, receipt or anything else yet. Narrow with filter; keys: period (named period such as this_year/prev_quarter, or a range like 20260101..20260131), state (all|new|saved|open|paid|late|pending_payment — paid, late and pending_payment only apply to purchase invoices and receipts), recurring (all|enabled|disabled), attachment (all|with|without), reference, contact_id, ledger_account_id, updated_after (ISO 8601 UTC).
Inputs: page, filter, per_page, administration_id.
list_usersList usersARead-onlyIdempotent
List the users with access to the administration, with their ids and permissions.
Inputs: administration_id.
moneybird_connection_statusMoneybird connection statusARead-onlyIdempotent
Report whether this server has working Moneybird credentials, which administration is selected, and which administrations the token can reach.
Inputs: no named parameters.
select_administrationSelect administrationARead-onlyIdempotent
Change the administration that tools use when they are not given an explicit administration_id. Applies for the rest of this session.
Inputs: administration_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 52 tools
Each resource has a clear list/get pair, and document types are explicitly named, so most tools are easy to tell apart. The main ambiguity is between get_sales_invoice and the two find_sales_invoice_by_* lookup tools, plus a few similarly filtered list_* document tools, but descriptions resolve these.
The dominant verb_noun pattern is consistent: list_*, get_*, find_*_by_*, download_*_pdf. A few deviations exist, most notably moneybird_connection_status which is a noun phrase rather than a verb-led action, but the naming is generally predictable.
52 tools is well beyond the 25+ threshold and feels heavy for an MCP surface, even for a broad domain like Moneybird. Many tools are mechanical list/get pairs that could be consolidated without losing clarity.
The server is almost entirely read-only: it lists and retrieves many entities but offers no way to create, update, delete, send, or pay invoices, contacts, purchases, or time entries. This leaves common Moneybird workflows dead-ended despite the wide read coverage.
Related MCP Connectors
Read-only access to Dutch accounting: Exact Online, Moneybird and SnelStart.
Free hosted MCP for invoices, estimates, clients, items and PDFs. OAuth authorization required.
Read e-Boekhouden relations, invoices, ledgers, bookings and products; create relations, invoices.
Connect Exact Online to your AI assistant via MCP. Manage Exact Online with natural language.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceHosted MCP server for Exact Online. Ask questions, pull reports, and prepare bookings you approve first.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible LLMs to interact with the MOCO ERP API, providing full read/write access to time tracking, projects, invoices, contacts, and other endpoints.25 npmISC
- AlicenseNot gradedqualityDmaintenanceEnables MCP-compatible agents to securely access an Invoice4U account for searching documents and customers and creating receipts linked to paid invoices, with read-only behavior by default.1MIT
- AlicenseNot gradedqualityAmaintenanceEnables LLMs to log and manage time entries, control timers, review unbilled hours, and prepare draft Moneybird invoices through natural language.1MIT