ohneben's Buchhaltungsbutler MCP

Manage your BuchhaltungsButler bookkeeping in plain language from AI assistants like Claude, Cursor, and any other MCP client.

This Model Context Protocol server exposes the BuchhaltungsButler API v1 — all 48 endpoints, auto-generated from the official OpenAPI spec into MCP tools. Every tool is safety-categorized (read-only / write / destructive) so your assistant knows what an action does before it calls it. Runs over stdio (Claude Desktop and other local launchers) or Streamable HTTP (hosted in Docker).

Why you'll want this

Some MCP servers just forward an API. This one is built to be safe to hand to an LLM and easy to run for real:

How it compares

At the time of writing this appears to be the only dedicated BuchhaltungsButler MCP server. You could instead point a generic OpenAPI→MCP wrapper at the spec — here's what that leaves on the table:

*Generic OpenAPI→MCP wrappers turn any Swagger/OpenAPI spec into MCP tools. They can reach the same endpoints, but treat every operation identically — no safety categories, no deployment story, and no guardrails tuned for live accounting data. "➖" = varies by tool / not guaranteed. Snapshot from July 2026.

Related MCP server: YNAB Assistant

What you can do

Once it's connected, ask your assistant things like:

• "List all inbound receipts from last month that are still unpaid."

• "Create a draft invoice for ACME GmbH: 10 hours of consulting at €120 each."

• "Book this bank transaction against posting account 4400."

• "Upload this PDF receipt and assign it to the matching transaction."

• "Show me my creditors, and add a new one for our hosting provider."

Tools are generated automatically from the official API and grouped into 🟢 read-only, 🟡 write, and 🔴 destructive — so a well-behaved host can treat each group differently.

How it works

Claude / Cursor / any MCP client  ──MCP──►  this server  ──HTTPS──►  BuchhaltungsButler API (cloud)

The server parses the bundled OpenAPI spec into MCP tools (resolving $ref batch payloads and stripping HTML from descriptions), tags each with its safety category, and injects your Basic-auth credentials and api_key on every outgoing request. Your credentials stay in the server's environment — the model never sees or handles them.

Requirements

• A BuchhaltungsButler account with API access — an API Client + API Secret (Settings → API) and a customer api_key (see Get your API credentials).

• Docker (Docker Desktop on macOS/Windows) for the quick start below — or Node.js ≥ 18 to run from source.

Quick start (Docker)

1. Add your credentials. Copy the example config and fill it in:

cp .env.example .env
# edit .env → set BB_API_CLIENT, BB_API_SECRET, BB_API_KEY
#           → set MCP_AUTH_TOKEN to a long random string if reachable beyond localhost

2. Start the server:

docker compose up -d --build

3. Confirm it's running:

curl -s http://localhost:3000/health     # → {"status":"ok","server":"buchhaltungsbutler-mcp"}

4. Connect your MCP client. Remote endpoints are added in Claude as a custom connector (Settings → Connectors), or bridged locally with mcp-remote. Add this under mcpServers in your client config, then fully quit and reopen the app:

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/mcp",
        "--header", "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"
      ]
    }
  }
}

(Drop the --header line if you left MCP_AUTH_TOKEN empty.)

Prefer a prebuilt image?

Every push to main publishes a ready-to-run image to the GitHub Container Registry, so you can skip the local build entirely:

docker run -d --name buchhaltungsbutler-mcp -p 3000:3000 --env-file .env \
  ghcr.io/ohneben/buchhaltungsbutler-mcp:latest

Get your API credentials

BuchhaltungsButler uses two layers of authentication (see the official docs):

1. HTTP Basic auth — an API Client + API Secret, your global API credentials. Find or create them in BuchhaltungsButler under Settings → API.

2. api_key — identifies which customer account a request acts on. It lives in that customer's company-data settings.

Put all three in .env. The server injects them on every request, so your assistant never sees them. A single tool call may optionally pass its own api_key to target a different customer.

Configuration

Everything is set in .env (copied from .env.example):

After changing .env, reload with docker compose up -d --force-recreate.

Tool safety categories

Each tool's description starts with one of these banners and carries the matching MCP annotations:

Hosts that respect annotations (Claude included) can require confirmation for destructiveHint tools and trust readOnlyHint tools automatically.

Run npm run list-tools (no credentials needed) to print the full catalog at any time.

Run from source (stdio, no Docker)

Prefer the classic stdio mode for Claude Desktop? Build it locally:

npm install
npm run build

Then point Claude Desktop at the compiled entrypoint in claude_desktop_config.json:

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/Buchhaltungsbutler MCP/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BB_API_CLIENT": "your-api-client",
        "BB_API_SECRET": "your-api-secret",
        "BB_API_KEY": "your-customer-api-key"
      }
    }
  }
}

Or run the container over stdio instead:

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "BB_API_CLIENT", "-e", "BB_API_SECRET", "-e", "BB_API_KEY",
        "buchhaltungsbutler-mcp:latest"
      ],
      "env": {
        "BB_API_CLIENT": "your-api-client",
        "BB_API_SECRET": "your-api-secret",
        "BB_API_KEY": "your-customer-api-key"
      }
    }
  }
}

(Build the image first: docker build -t buchhaltungsbutler-mcp:latest .)

Keeping the spec current

The bundled spec.json is the official BuchhaltungsButler v1 OpenAPI spec — the source of truth for the tools. To refresh against a newer API version:

curl -s https://app.buchhaltungsbutler.de/docs/api/v1.de.json -o spec.json
npm run build

New paths are picked up automatically; add them to PATH_CATEGORY in src/categories.ts so they get the correct safety category (unmapped paths fall back to the safe-but-conservative create category).

Development

npm install
npm run build      # compile TypeScript → dist/
npm test           # run the Vitest suite
npm run list-tools # print the categorized tool catalog (no credentials needed)

CI builds and tests every push across Node 20 and 22; pushes to main also publish a Docker image to the GitHub Container Registry.

Notes & conventions

• Dates: YYYY-MM-DD. Amounts: dot decimal separator (e.g. -12.30).

• File uploads (receipts_upload, receipts_add, receipts_addBatch): pass the file as a base64 string in the file field.

• Paging: most get tools accept limit and offset.

• Batch tools take arrays of objects; item schemas are resolved from the spec definitions and shown to the model.

• Rate limit: BuchhaltungsButler allows 100 requests/customer/minute; the server self-throttles at BB_RATE_LIMIT (default 90) to stay safely under it.

Security

• Your API credentials live only in .env, which is git-ignored. Never commit real secrets. If any leak, rotate them in BuchhaltungsButler → Settings → API.

• The HTTP endpoint is unauthenticated by default (fine on localhost). To expose it beyond your machine, set MCP_AUTH_TOKEN and send it as an Authorization: Bearer <token> header — ideally behind TLS.

See SECURITY.md for the full policy and how to report a vulnerability.

Credits & license

An unofficial community integration for BuchhaltungsButler; not affiliated with or endorsed by BuchhaltungsButler. Built on the Model Context Protocol. Licensed under the MIT License.