ohneben's Buchhaltungsbutler MCP

Lizenz & Checks

MCP-Register

Paketkennungen

Dieser Server hat eigene Kennungen. Was anders heißt, gehört nicht dazu:

Das npm-Paket buchhaltungsbutler-mcp ohne Scope ist ein anderes Projekt eines anderen Autors (mrvnklm/buchhaltungsbutler-mcp) und hat mit diesem hier nichts zu tun. Verzeichnisse, die von dieser Seite dorthin verlinken, verlinken auf das falsche Paket.

Verwalte deine BuchhaltungsButler-Buchhaltung in natürlicher Sprache aus KI-Assistenten wie Claude, Cursor und jedem anderen MCP-Client.

Dieser Model-Context-Protocol-Server stellt die BuchhaltungsButler API v1 bereit — alle 54 Endpunkte als 46 MCP-Tools, aus der offiziellen OpenAPI-Spezifikation (Spec-Version 1.9.1) generiert. Jedes Tool ist sicherheitskategorisiert (nur lesend / schreibend / destruktiv), damit dein Assistent weiß, was eine Aktion tut, bevor er sie ausführt. Läuft über stdio (Claude Desktop und andere lokale Launcher) oder Streamable HTTP (gehostet in Docker).

Warum dieser Server

Manche MCP-Server leiten eine API einfach nur weiter. Dieser hier ist darauf ausgelegt, gefahrlos an ein Sprachmodell übergeben und im Alltag betrieben werden zu können:

Im Vergleich

Nach aktuellem Stand ist dies der einzige dedizierte BuchhaltungsButler-MCP-Server. Alternativ könntest du einen generischen OpenAPI→MCP-Wrapper auf die Spec richten — das lässt allerdings einiges liegen:

_{*Generische OpenAPI→MCP-Wrapper machen aus jeder Swagger-/OpenAPI-Spec MCP-Tools. Sie erreichen dieselben Endpunkte, behandeln aber jede Operation gleich — keine Sicherheitskategorien, keine Betriebsgeschichte, keine auf echte Buchhaltungsdaten abgestimmten Leitplanken. „➖“ = je nach Werkzeug unterschiedlich / nicht garantiert.}

Was du damit machen kannst

Sobald der Server verbunden ist, kannst du deinen Assistenten zum Beispiel bitten:

• „Liste alle Eingangsbelege vom letzten Monat auf, die noch offen sind.“
• „Erstelle einen Rechnungsentwurf für die ACME GmbH: 10 Stunden Beratung à 120 €.“
• „Buche diese Banktransaktion auf Sachkonto 4400.“
• „Lade diesen PDF-Beleg hoch und ordne ihn der passenden Transaktion zu.“
• „Zeig mir meine Kreditoren und leg einen neuen für unseren Hosting-Anbieter an.“
• „Erstelle mir die BWA für das letzte Quartal und zeig mir das Kontenblatt zu Konto 4400.“

Die Tools werden automatisch aus der offiziellen API generiert und in 🟢 nur lesend, 🟡 schreibend und 🔴 destruktiv gruppiert — ein gut umgesetzter Host kann jede Gruppe unterschiedlich behandeln.

Funktionsweise

Claude / Cursor / beliebiger MCP-Client  ──MCP──►  dieser Server  ──HTTPS──►  BuchhaltungsButler API (Cloud)

Der Server liest die mitgelieferte OpenAPI-Spec ein und macht daraus MCP-Tools (inklusive Auflösung von $ref-Batch-Payloads und Entfernen von HTML aus den Beschreibungen), versieht jedes Tool mit seiner Sicherheitskategorie und hängt deine Basic-Auth-Credentials sowie den api_key an jede ausgehende Anfrage. Deine Zugangsdaten bleiben in der Server-Umgebung — das Modell sieht sie nie und fasst sie nie an.

Voraussetzungen

• Ein BuchhaltungsButler-Konto mit API-Zugang — ein API Client + API Secret (Einstellungen → API) sowie ein Kunden-api_key (siehe API-Zugangsdaten besorgen).
• Docker (Docker Desktop unter macOS/Windows) für den Schnellstart unten — oder Node.js ≥ 18, um aus dem Quellcode zu starten.

Schnellstart (Docker)

1. Zugangsdaten hinterlegen. Beispielkonfiguration kopieren und ausfüllen:

cp .env.example .env
# .env bearbeiten → BB_API_CLIENT, BB_API_SECRET, BB_API_KEY setzen
#                 → MCP_AUTH_TOKEN setzen. PFLICHT, sonst startet der Server
#                   nicht, denn .env.example bindet auf 0.0.0.0:
#                   openssl rand -hex 32

2. Server starten:

docker compose up -d --build

3. Prüfen, ob er läuft:

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

4. MCP-Client verbinden. Entfernte Endpunkte werden in Claude als Custom Connector hinzugefügt (Einstellungen → Connectors) oder lokal mit mcp-remote gebrückt. Trage Folgendes unter mcpServers in deiner Client-Konfiguration ein und starte die App danach vollständig neu:

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

(Die --header-Zeile entfällt nur, wenn du ohne Token auf Loopback bindest. Im Docker-Schnellstart oben ist das Token Pflicht.)

Lieber ein fertiges Image?

Jeder Push auf main veröffentlicht ein startbereites Image in der GitHub Container Registry — damit kannst du den lokalen Build komplett überspringen:

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

API-Zugangsdaten besorgen

BuchhaltungsButler nutzt zwei Authentifizierungsebenen (siehe die offizielle Dokumentation):

1. HTTP-Basic-Auth — ein API Client + API Secret, deine globalen API-Zugangsdaten. Zu finden bzw. anzulegen in BuchhaltungsButler unter Einstellungen → API.
2. api_key — legt fest, auf welches Kundenkonto sich eine Anfrage bezieht. Er steht in den Firmendaten-Einstellungen des jeweiligen Kunden.

Trage alle drei Werte in .env ein. Der Server hängt sie an jede Anfrage an, dein Assistent bekommt sie also nie zu sehen. Ein einzelner Tool-Aufruf kann optional einen eigenen api_key mitgeben, um ein anderes Kundenkonto anzusprechen.

Konfiguration

Alles wird in .env gesetzt (kopiert aus .env.example):

Nach Änderungen an .env neu laden mit docker compose up -d --force-recreate.

Toolnamen

Jedes Tool heißt <ressource>_<verb>. Die Verben sind fest: list, get, create, update, delete, upload, assign, unassign, unconfirm, restore, cancel. Damit heißt dieselbe Sache überall gleich, unabhängig davon, wie der jeweilige BB-Pfad geschrieben ist (die API mischt add und create, und zwei Batch-Pfade sind camelCase).

Anlegen geht immer über ein Tool, das eine Liste nimmt. receipts_create legt einen Beleg oder hundert an, ein einzelner Datensatz ist eine Liste mit einem Eintrag. Deshalb gibt es 46 Tools für 54 Endpunkte: acht Einzel-Endpunkte sind in ihrem Batch-Gegenstück aufgegangen.

Alte Namen bleiben aufrufbar

Die Namen bis 1.1.1 funktionieren weiter. Sie stehen nicht mehr im Katalog, werden aber beim Aufruf aufgelöst, damit fest verdrahtete Aufrufe aus älteren Releases nicht ins Leere laufen. Ein Aufruf von receipts_add mit Einzelfeldern landet weiterhin auf /receipts/add.

BB_READ_ONLY und BB_TOOL_ALLOWLIST greifen vorher: über einen alten Namen lässt sich kein Tool erreichen, das die Policy ausschließt.

Die vollständige Zuordnung steht in src/naming.ts.

Sicherheitskategorien der Tools

Jede Tool-Beschreibung beginnt mit einem dieser Banner und trägt die passenden MCP-Annotationen:

Hosts, die Annotationen respektieren (Claude gehört dazu), können für destructiveHint-Tools eine Bestätigung verlangen und readOnlyHint-Tools automatisch vertrauen.

Jedes Tool bringt zusätzlich ein outputSchema mit, also die Form der Erfolgsantwort. Erfolgreiche Aufrufe liefern die Antwort deshalb nicht nur als Text, sondern auch als structuredContent.

Mit npm run list-tools (ohne Zugangsdaten) lässt sich der vollständige Katalog jederzeit ausgeben.

Was die v1-API nicht kann

Diese Lücken stehen absichtlich auch in den Tool-Beschreibungen, damit das Modell nicht nach einem Endpunkt sucht, den es nicht gibt:

Aus dem Quellcode starten (stdio, ohne Docker)

Du bevorzugst den klassischen stdio-Modus für Claude Desktop? Dann lokal bauen:

npm install
npm run build

Anschließend Claude Desktop in claude_desktop_config.json auf den kompilierten Einstiegspunkt zeigen lassen:

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/ABSOLUTER/PFAD/Buchhaltungsbutler MCP/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BB_API_CLIENT": "dein-api-client",
        "BB_API_SECRET": "dein-api-secret",
        "BB_API_KEY": "dein-kunden-api-key"
      }
    }
  }
}

Oder den Container stattdessen über stdio betreiben:

{
  "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": "dein-api-client",
        "BB_API_SECRET": "dein-api-secret",
        "BB_API_KEY": "dein-kunden-api-key"
      }
    }
  }
}

(Das Image vorher bauen: docker build -t buchhaltungsbutler-mcp:latest .)

Spec aktuell halten

Die mitgelieferte spec.json ist die offizielle BuchhaltungsButler-v1-OpenAPI-Spec — die maßgebliche Quelle für die Tools. So aktualisierst du sie auf einen neueren API-Stand:

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

Neue Pfade werden automatisch übernommen; trage sie in PATH_CATEGORY in src/categories.ts ein, damit sie die richtige Sicherheitskategorie bekommen (nicht zugeordnete Pfade fallen konservativ auf die Kategorie create zurück).

Hinweis zur Versionsnummer: BuchhaltungsButler pflegt das Feld info.version in der Spec nicht zuverlässig — der Inhalt kann sich ändern, ohne dass die Nummer steigt. Verlass dich beim Abgleich also nicht auf die Version, sondern vergleiche die Pfadliste (paths) und die Parameter der Endpunkte.

Entwicklung

Hinweise zu korrigierten Buchungs- und Zuordnungsantworten, Teilfehlern und unklarem Schreibausgang: Belege buchen und Zahlungen zuordnen.

npm install
npm run build      # TypeScript → dist/ kompilieren
npm test           # Vitest-Suite ausführen
npm run list-tools # kategorisierten Tool-Katalog ausgeben (ohne Zugangsdaten)

Die CI baut und testet jeden Push unter Node 20 und 22; Pushes auf main veröffentlichen zusätzlich ein Docker-Image in der GitHub Container Registry.

Für eine ergänzende Prüfung mit einem eigenen API-Zugang siehe Lesende API-/MCP-Verifikation. Die normale Testsuite verwendet synthetische Daten und benötigt keine Zugangsdaten.

Hinweise & Konventionen

• Datumsangaben: YYYY-MM-DD. Beträge: Punkt als Dezimaltrennzeichen (z. B. -12.30).
• Datei-Uploads (receipts_upload): Die Datei wird als Base64-Zeichenkette im Feld file übergeben. receipts_create legt Belege ohne Datei an.
• Blättern: Die meisten list-Tools akzeptieren limit und offset. Bei den geprüften Beleg-, Transaktions- und Buchungslisten zählt rows nur die aktuelle Seite, nicht den Gesamtbestand. Wiederholte IDs und fehlenden Fortschritt erkennen. Eine leere Abschlussseite und Deduplizierung beweisen keine Vollständigkeit: gefilterte Transaktionsseiten haben sich im Praxistest überschnitten, während andere IDs fehlten. Für transactions_list bevorzugt id_by_customer_from mit konstanten Filtern und limit, ohne offset, nutzen: Der Cursor ist exklusiv und erzwingt aufsteigende ID-Sortierung. Bei 0 beginnen, anschließend die größte erhaltene ID unverändert als nächsten Cursor setzen; IDs und Fortschritt prüfen, bis zur leeren Seite fortsetzen und unabhängig abstimmen. Details und Grenzen: lesende Verifikation.
• Einzelabrufe: receipts_get_by_id und transactions_get_by_id benötigen id_by_customer als positive ganze Zahl aus dem jeweiligen Listentool. Der Server setzt diese Nummer in den API-Pfad ein.
• Anlegen geht immer über ein Tool, das ein Array nimmt; die Item-Schemata werden aus den Spec-Definitionen aufgelöst und dem Modell mitgegeben. Ein einzelner Datensatz ist ein Array mit einem Eintrag.
• Auswertungen (BWA, Summen- und Saldenliste) werden asynchron im Hintergrund erzeugt: erst reports_create_* aufrufen, dann reports_get_* mit der zurückgegebenen id_by_customer. Eine neue Auswertung desselben Typs ersetzt die vorherige.
• Kontenblatt: reports_get_sums_ledger benötigt nur Buchungskontonummer und Zeitraum; die API liefert es direkt, ohne vorher erzeugte SuSa und ohne Berichts-ID.
• Rate-Limit: BuchhaltungsButler erlaubt 100 Anfragen/Kunde/Minute; der Server drosselt sich selbst bei BB_RATE_LIMIT (Standard 90), um sicher darunter zu bleiben.

Sicherheit

• Deine API-Zugangsdaten liegen ausschließlich in .env, und diese Datei ist von Git ausgeschlossen. Committe niemals echte Geheimnisse. Falls doch etwas abfließt, rotiere die Daten unter BuchhaltungsButler → Einstellungen → API.
• Der HTTP-Endpunkt verlangt ein Token, sobald er über Loopback hinaus gebunden ist. Ohne MCP_AUTH_TOKEN verweigert der Server den Start und erklärt im Fehlertext, was zu tun ist. Sende das Token als Authorization: Bearer <Token>-Header, idealerweise hinter TLS.
• Auch auf localhost gilt: ohne Token wird der Host-Header auf localhost-Namen begrenzt, damit keine beliebige Webseite den Endpunkt per DNS-Rebinding ansprechen kann. Hinter einem Reverse-Proxy setzt du dafür MCP_ALLOWED_HOSTS.
• Hinter einem Reverse-Proxy setzt du den Host-Header im Proxy am besten fest auf den internen Upstream-Namen und trägst genau diesen in MCP_ALLOWED_HOSTS ein. Dann hängt die Prüfung nicht an der öffentlichen Domain und übersteht einen Domainwechsel. (Tipp von @WinFuture23.)
• Setzt du MCP_ALLOWED_HOSTS und hat deine Plattform einen HTTP-Health-Check, muss dessen Hostname mit in die Liste. Railway sendet Host: healthcheck.railway.app, Kubernetes-Probes fragen je nach Konfiguration über die Container-IP an. Fehlt der Name, bekommt der Health-Check eine 403 und die Plattform wertet das Deployment als kaputt.
• /health liegt hinter der Host-Prüfung, aber vor der Token-Prüfung: ein Health-Check der Plattform braucht kein Token. Zusätzlich akzeptiert /health immer localhost, 127.0.0.1 und [::1], damit der HEALTHCHECK aus dem mitgelieferten Dockerfile weiterläuft, wenn du MCP_ALLOWED_HOSTS auf deine öffentliche Domain setzt. Fragt dein Health-Check dagegen über die Container-IP oder einen Service-Namen an, musst du diesen Namen in MCP_ALLOWED_HOSTS aufnehmen.
• Der api_key pro Tool-Aufruf ist standardmäßig deaktiviert (BB_ALLOW_API_KEY_OVERRIDE=1 schaltet ihn frei), damit das Modell nicht selbst entscheiden kann, auf welchen Mandanten geschrieben wird.

Die vollständige Richtlinie und den Meldeweg für Sicherheitslücken findest du in SECURITY.md.

Credits & Lizenz

Eine inoffizielle Community-Integration für BuchhaltungsButler; weder mit BuchhaltungsButler verbunden noch von dort unterstützt. Basiert auf dem Model Context Protocol. Veröffentlicht unter der MIT-Lizenz.