Moneybird MCP

Language: English · Nederlands

Unofficial community integration. This project is not developed, endorsed, supported, or audited by Moneybird B.V.

Beta 0.8.1. The supported setup is a local MCP server over stdio. It starts mechanically read-only. Experimental writes require an explicit local opt-in and supervised approval.

Use Claude, ChatGPT, Cursor, or another MCP client to search and work with a Moneybird administration. The server can read contacts, invoices, documents, bank mutations, reports, and locally indexed bookkeeping data.

Get started

You need Python 3.11 or newer, an MCP client, and a fresh Moneybird API token.

Recommended: run with uvx

Add this server configuration to your MCP client:

{
  "mcpServers": {
    "moneybird": {
      "command": "uvx",
      "args": ["moneybird-mcp"],
      "env": {
        "MONEYBIRD_ACCESS_TOKEN": "your-token-here",
        "MONEYBIRD_ADMINISTRATION_ID": "optional"
      }
    }
  }
}

Restart the client and ask it to list your Moneybird administrations.

MONEYBIRD_ADMINISTRATION_ID is optional when the token can access only one administration. Never paste a real Moneybird token into a chat, issue, log, or committed file.

A personal API token is the simple, supported way to run this locally: it is one credential you already control, with no application registration involved.

Optional: OAuth with your own registered application

For development, or for self-hosters who want refresh tokens and scoped access, the server can connect through Moneybird's OAuth flow using an OAuth application you register yourself:

moneybird-mcp auth login --env-file /absolute/path/moneybird-mcp.env
moneybird-mcp auth status
moneybird-mcp auth logout

This is not the default public setup, and there is no shared application credential in the package. An OAuth Client Secret authenticates the application rather than the user, so it cannot be shipped inside an installable package — anything distributed to every user is not a secret. Running OAuth locally therefore means bringing your own Client ID and Client Secret.

When both a personal token and an OAuth connection exist, the personal token wins; moneybird-mcp auth status says which one is active. Full detail: Moneybird OAuth.

Claude Code registrations are scoped. Its default local scope is available only in the current project; use --scope user when Moneybird should be available from every project. If claude mcp list says connected but a different project shows no tools, check claude mcp get moneybird and re-add the configuration at user scope. Do not use project scope for a configuration containing a personal token, because project scope writes a shared .mcp.json file.

Install with pip

python -m pip install --upgrade moneybird-mcp
moneybird-mcp

For PDF attachment reading:

python -m pip install --upgrade "moneybird-mcp[pdf]"

Package page: moneybird-mcp on PyPI

On Windows, quit every MCP client that is running moneybird-mcp before installing or upgrading with pip; Windows cannot replace the locked console executable. If pip reports WinError 32, keep the client closed and run the install command again to repair the partial installation. The recommended uvx setup avoids upgrading that in-use console script.

Upgrade

With pip:

python -m pip install --upgrade moneybird-mcp

On Windows, close the MCP client first. If an earlier attempt failed with WinError 32, rerun the same command while the client remains closed.

To force uvx to refresh its cached package metadata:

uvx --refresh-package moneybird-mcp moneybird-mcp

Check the installed command and available options:

moneybird-mcp --help

What it can do

• Search contacts, sales invoices, purchase invoices, receipts, general journals, and bank mutations.
• Match unprocessed bank transactions to the open invoices they settle, with the evidence for each candidate, and say so plainly when two candidates fit equally well.
• Read Moneybird reports, including profit and loss, balance sheet, general ledger, VAT, debtor, and creditor reports.
• Review purchase invoices, invoice-delivery settings, bank mutations, and bookkeeping inconsistencies.
• Settle one purchase invoice from an exact group of bank mutations with one preview and approval, including final invoice processing and verification.
• Audit product data and calculate guarded bulk price changes with exact decimal previews.
• Read PDF attachments locally when the optional PDF dependency is installed.
• Build a local search index for faster ranked search.
• Read the Dutch bookkeeping playbook per topic (VAT, VAT settlement, bank matching, categorisation, consistency) as a tool, not only as an MCP resource.
• Prepare guarded write previews when writes have been explicitly enabled.

The server advertises its full tool catalogue by default: tool schemas live in the client's cached prompt prefix, so listing them is cheap, while discovering them on demand costs an extra model round trip on every task. Clients that cannot take the full list can run --tool-discovery search for compact Tool Search. See the tool reference and Moneybird API coverage.

Use list_supported_workflows to discover the small set of outcomes that are integrated and tested end to end. The generated workflow catalogue records their risk, mode, version, prerequisites, verification, and limitations. Product tools perform their concrete administration and record preflight themselves.

Read-only and write modes

The server starts mechanically read-only. This is the default and needs no flag:

MONEYBIRD_CAPABILITY_MODE=read_only

Experimental writes are available only in local or authenticated single-user deployments:

MONEYBIRD_CAPABILITY_MODE=write_enabled

Writes use durable prepare/execute approvals and action-specific verification. This is safety machinery, not independent proof that a human approved the action. Keep destructive-tool confirmation enabled in the MCP client and review every preview.

Configuration

The most useful settings are:

The package never discovers .env files automatically. Use an MCP-client environment block or an explicitly selected file:

moneybird-mcp --env-file /absolute/path/moneybird-mcp.env

See Getting started for complete setup examples.

Deployment boundary

Every HTTP/SSE listener requires MCP_AUTH_TOKEN, including loopback. Non-loopback listeners are refused unless a trusted TLS proxy is explicitly configured. The network transport is intended for one trusted user and does not provide multi-user identity or tenant isolation.

See Deployment and safety, Security policy, and the threat model.

Local data

Installed stdio runs store local state in ~/.moneybird-mcp unless MONEYBIRD_MCP_DATA_DIR is set. This can include:

• OAuth access and refresh tokens;
• the approvals SQLite database;
• per-administration audit logs;
• search indexes and caches;
• privacy-safe local telemetry.

These files are not encrypted by this project. Restrict access to the directory and read Local data lifecycle before backing up or deleting it.

Documentation

• Getting started
• Connecting through Moneybird OAuth
• Tool reference
• Deployment and safety
• Local data lifecycle
• Security policy
• Support
• Contributing
• Changelog
• Moneybird API coverage
• Release process

Support and status

This is a pre-1.0 community project. There is no guaranteed response time, uptime, data recovery, bookkeeping correctness, or tax advice.

Use GitHub Issues for reproducible bugs and feature requests without secrets or customer data. Report vulnerabilities privately as described in SECURITY.md.

Licence

This project is source-available, not OSI-approved open source. It is distributed under the MIT License with the Commons Clause License Condition v1.0.

Personal use, internal organisational use, inspection, and modification are permitted. Selling the software, commercially providing its functionality as a service, or commercially repackaging it requires a separate commercial licence. For commercial licensing, contact the repository owner through GitHub Issues. The complete terms in LICENSE govern.