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.

Tools mit zwei Endpunkten nehmen eine Liste. Kommt der Aufruf stattdessen mit
Einzelfeldern, geht er an den Einzel-Endpunkt.

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.