mcp-buchhaltungsbutler

Deutsch | English

Ein MCP (Model Context Protocol) Server, der die BuchhaltungsButler API (v1) – eine deutsche Buchhaltungs-/Accounting-SaaS – als eine Reihe kuratierter, token-effizienter Tools für LLM-Agenten bereitstellt.

Inoffizielles Community-Projekt. Nicht verbunden mit oder unterstützt von BuchhaltungsButler.

Für Agenten gebaut, nicht nur von der API umhüllt

• 30 Tools, die alle 48 Endpunkte abdecken – Batch-, Listen- und Einzelvarianten derselben Aktion werden zu einem Tool zusammengeführt, sodass Ihr Kontextfenster nicht mit fast identischen Tool-Definitionen gefüllt ist.

• Schlank standardmäßig – Listentools liefern standardmäßig reduzierte, LLM-freundliche Felder; übergeben Sie full: true, wenn Sie den vollständigen Datensatz benötigen.

• Kein Array-Jonglieren – Rechnungspositionen, Buchungssplits und andere API-Eigenheiten werden als saubere, gewöhnliche Objekte bereitgestellt. Kein manuelles Synchronisieren von fünf parallelen Arrays mehr.

• Immer synchron mit der Spezifikation – Endpunktdefinitionen werden direkt aus der offiziellen API-Spezifikation von BuchhaltungsButler generiert, nicht manuell gepflegt.

Related MCP server: Cuéntica MCP

Einrichtung

1. npm install

2. Kopieren Sie .env.example in .env und füllen Sie BB_API_CLIENT, BB_API_SECRET, BB_API_KEY aus (BuchhaltungsButler → Einstellungen → API).

3. npm test – läuft gegen simulierte HTTP-Antworten, keine echten Anmeldedaten erforderlich.

4. npm run build && npm start – oder npm run dev für einen schnellen lokalen Lauf ohne vorheriges Build.

npm run generate regeneriert src/bb-client/generated/endpoints.ts aus der mitgelieferten Spezifikation (spec/buchhaltungsbutler-v1.json); die Ausgabe ist bereits eingecheckt, daher ist dies nur nach dem Aktualisieren der Spezifikationsdatei selbst erforderlich.

Verwendung mit einem MCP-Client

.env deckt nur lokale npm run dev/npm start-Läufe ab. Ein echter MCP-Client (z. B. Claude Desktop) startet den Server selbst und liest .env nicht – übergeben Sie Anmeldedaten stattdessen über die eigene env-Konfiguration des Clients. Beispiel für einen Eintrag in claude_desktop_config.json:

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-buchhaltungsbutler/dist/index.js"],
      "env": {
        "BB_API_CLIENT": "your-api-client",
        "BB_API_SECRET": "your-api-secret",
        "BB_API_KEY": "your-customer-api-key"
      }
    }
  }
}

Führen Sie zuerst npm run build aus, damit dist/index.js existiert.

Werkzeuge

Architektur

src/
  config.ts              # env var loading, fail-fast validation
  bb-client/
    generated/            # spec-derived endpoint metadata (regenerate with npm run generate)
    client.ts              # generic HTTP client: auth, api_key injection, error mapping
  formatting/trim.ts       # trims list responses to LLM-friendly fields
  tools/                   # one file per category, curated MCP tools on top of the client
  server.ts, index.ts      # MCP server bootstrap (stdio)
scripts/generate-client.ts # parses spec/buchhaltungsbutler-v1.json into src/bb-client/generated/

Single-Tenant, nur lokaler stdio-Transport – kein Remote-Hosting, keine Multi-Tenant-Unterstützung, kein OAuth. Anmeldedaten erreichen niemals das Modell; sie werden von der Client-Schicht aus Umgebungsvariablen in die Anfragen eingefügt.

Status

Alle 48 BuchhaltungsButler-Endpunkte werden von den 30 oben genannten Tools abgedeckt, getestet gegen simulierte HTTP-Antworten. Noch nicht gegen ein Live-Konto verifiziert – wenn Sie auf einen unerwarteten Fehler stoßen, insbesondere bei den vier Endpunkten mit *_id_by_customer-Suffix (get_receipt, set_receipt_deleted, get_transaction) oder bei add_receipt_postings/add_transaction_postings mit einer gemischten Kostenstellen-Batch, eröffnen Sie bitte ein Issue.

Entwicklung

git clone https://github.com/si0nDE/mcp-buchhaltungsbutler.git && cd mcp-buchhaltungsbutler
npm install
npm test           # vitest run
npm run build       # tsc, strict mode