Metadata-Version: 2.4
Name: moneybird-mcp
Version: 0.7.0
Summary: Read-first MCP server for Moneybird bookkeeping, with experimental supervised writes behind an explicit capability policy.
Project-URL: Homepage, https://github.com/Espaye/moneybird-mcp-server
Project-URL: Repository, https://github.com/Espaye/moneybird-mcp-server
Project-URL: Issues, https://github.com/Espaye/moneybird-mcp-server/issues
Project-URL: PyPI, https://pypi.org/project/moneybird-mcp/
Project-URL: Documentation, https://github.com/Espaye/moneybird-mcp-server#readme
Project-URL: Changelog, https://github.com/Espaye/moneybird-mcp-server/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/Espaye/moneybird-mcp-server/security/policy
Author: Espaye
License-Expression: LicenseRef-MIT-Commons-Clause-1.0
License-File: LICENSE
Keywords: accounting,bookkeeping,invoicing,mcp,model-context-protocol,moneybird
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.11
Requires-Dist: fastmcp<4,>=3.4.5
Requires-Dist: httpx<1,>=0.28.1
Requires-Dist: pydantic<3,>=2.11.7
Requires-Dist: uvicorn>=0.35
Provides-Extra: pdf
Requires-Dist: pypdf>=6.15.0; extra == 'pdf'
Description-Content-Type: text/markdown

# Moneybird MCP

**Language:** **English** · [Nederlands](https://github.com/Espaye/moneybird-mcp-server/blob/main/README.nl.md)

[![PyPI](https://img.shields.io/pypi/v/moneybird-mcp.svg)](https://pypi.org/project/moneybird-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/moneybird-mcp.svg)](https://pypi.org/project/moneybird-mcp/)
[![CI](https://github.com/Espaye/moneybird-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/Espaye/moneybird-mcp-server/actions/workflows/ci.yml)

> **Unofficial community integration.** This project is not developed, endorsed, supported, or audited by Moneybird B.V.
>
> **Beta 0.7.0.** 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](https://developer.moneybird.com/authentication).

### Recommended: run with `uvx`

Add this server configuration to your MCP client:

```json
{
  "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**:

```bash
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](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/oauth.md).

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`

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

For PDF attachment reading:

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

Package page: [moneybird-mcp on PyPI](https://pypi.org/project/moneybird-mcp/)

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`:

```bash
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:

```bash
uvx --refresh-package moneybird-mcp moneybird-mcp
```

Check the installed command and available options:

```bash
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.
- 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](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/tool-reference.md) and [Moneybird API coverage](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/moneybird_api_coverage.md).

Use `list_supported_workflows` to discover the small set of outcomes that are integrated and tested end to end. The generated [workflow catalogue](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/workflow-catalogue.md) 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:

```text
MONEYBIRD_CAPABILITY_MODE=read_only
```

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

```text
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:

| Setting | Default | Purpose |
|---|---|---|
| `MONEYBIRD_ACCESS_TOKEN` | none | Moneybird personal API token; takes precedence over an OAuth connection |
| `MONEYBIRD_ADMINISTRATION_ID` | the one chosen at OAuth login, else automatic when unambiguous | Administration to use |
| `MONEYBIRD_OAUTH_CLIENT_ID` / `_SECRET` | none | Your own registered OAuth application, for `auth login` |
| `MONEYBIRD_OAUTH_SCOPES` | `full` | Scope profile or explicit list requested at login |
| `MONEYBIRD_OAUTH_PROFILE` | `default` | Which stored OAuth connection this server uses; `auth login --profile` writes it |
| `MONEYBIRD_CAPABILITY_MODE` | `read_only` | `read_only` or `write_enabled` |
| `MONEYBIRD_MCP_DATA_DIR` | `~/.moneybird-mcp` for the installed command | Local approvals, audit, OAuth, and search state |
| `MCP_TOOL_DISCOVERY` | `search` | Compact discovery; use `full` for older clients |
| `MCP_TRANSPORT` | `stdio` | `stdio`, `http`, or legacy `sse` |

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

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

See [Getting started](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/getting-started.md) for complete setup examples.

## Deployment boundary

| Mode | Intended use | Status |
|---|---|---|
| Local stdio | One user on one machine | Supported default |
| Authenticated HTTP/SSE | One trusted user behind authentication and TLS | Experimental |

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](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/deployment-and-safety.md), [Security policy](https://github.com/Espaye/moneybird-mcp-server/blob/main/SECURITY.md), and the [threat model](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/threat_model.md).

## 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](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/data-lifecycle.md) before backing up or deleting it.

## Documentation

- [Getting started](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/getting-started.md)
- [Connecting through Moneybird OAuth](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/oauth.md)
- [Tool reference](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/tool-reference.md)
- [Deployment and safety](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/deployment-and-safety.md)
- [Local data lifecycle](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/data-lifecycle.md)
- [Security policy](https://github.com/Espaye/moneybird-mcp-server/blob/main/SECURITY.md)
- [Support](https://github.com/Espaye/moneybird-mcp-server/blob/main/SUPPORT.md)
- [Contributing](https://github.com/Espaye/moneybird-mcp-server/blob/main/CONTRIBUTING.md)
- [Changelog](https://github.com/Espaye/moneybird-mcp-server/blob/main/CHANGELOG.md)
- [Moneybird API coverage](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/moneybird_api_coverage.md)
- [Release process](https://github.com/Espaye/moneybird-mcp-server/blob/main/docs/releasing.md)

## 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](https://github.com/Espaye/moneybird-mcp-server/issues) for reproducible bugs and feature requests without secrets or customer data. Report vulnerabilities privately as described in [SECURITY.md](https://github.com/Espaye/moneybird-mcp-server/blob/main/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](https://github.com/Espaye/moneybird-mcp-server/issues). The complete terms in [LICENSE](https://github.com/Espaye/moneybird-mcp-server/blob/main/LICENSE) govern.
