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, tools are grouped into toolsets you can enable individually, 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 serve

Then 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 login

which 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 status

status 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: kalender.digital 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 --oauth

The 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

Commands

Flags

Toolsets

Tools are grouped by Moneybird's own domains. Five are enabled by default; the other four are opt-in.

Set them explicitly, add to the defaults, or subtract from them:

moneybird-mcp serve --toolsets core,invoicing     # exactly these two
moneybird-mcp serve --toolsets all                # everything
moneybird-mcp serve --toolsets reports            # exactly reports
moneybird-mcp serve --toolsets -banking,-time     # the defaults minus two

A -name entry anywhere in the list means the list starts from the defaults rather than from nothing. all wins over everything else. An 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-write or MONEYBIRD_ALLOW_WRITE=true.

• destroy — needs --allow-delete and --allow-write. --allow-delete on 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 serve

Client setup

Claude Code

claude mcp add moneybird -- npx -y moneybird-mcp serve

With write access and a wider tool selection:

claude mcp add moneybird \
  --env MONEYBIRD_ALLOW_WRITE=true \
  --env MONEYBIRD_TOOLSETS=all \
  -- npx -y moneybird-mcp serve

Claude 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-mcp

The 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 format

docs/tools.md is generated from the tool definitions. Regenerate it after adding or changing a tool:

npm run docs:tools

spec/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 test

A 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.