BuchhaltungsButler MCP-Server

Ein Model Context Protocol (MCP)-Server für die BuchhaltungsButler API. Damit kannst du BuchhaltungsButler direkt aus Claude Desktop, ChatGPT oder jedem anderen MCP-Client heraus nutzen.

Voraussetzungen

• Node.js ≥ 18
• BuchhaltungsButler API-Zugang (API Client + API Secret + API Key eines Kunden)

Installation

git clone <repo-url>
cd buchhaltungsbutler-mcp
npm install
npm run build

Konfiguration

Die folgenden Umgebungsvariablen werden benötigt:

Variable	Beschreibung
BUCHHALTUNGSBUTLER_API_CLIENT	Dein API Client
BUCHHALTUNGSBUTLER_API_SECRET	Dein API Secret
BUCHHALTUNGSBUTLER_API_KEY	Der API-Key des zu verwaltenden Kunden (kann pro Tool-Aufruf überschrieben werden)

Optional:

Variable	Beschreibung
BUCHHALTUNGSBUTLER_API_URL	Standard: https://webapp.buchhaltungsbutler.de/api/v1

Verwendung in Claude Desktop

1. Öffne die Claude Desktop Konfiguration:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Füge den Server hinzu:

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/absoluter/pfad/zu/buchhaltungsbutler-mcp/dist/index.js"],
      "env": {
        "BUCHHALTUNGSBUTLER_API_CLIENT": "dein-api-client",
        "BUCHHALTUNGSBUTLER_API_SECRET": "dein-api-secret",
        "BUCHHALTUNGSBUTLER_API_KEY": "kunden-api-key"
      }
    }
  }
}

3. Claude Desktop neu starten.

Verwendung in ChatGPT / anderen Clients

Dieser Server verwendet den MCP-Stdio-Transport, der von Claude Desktop nativ unterstützt wird. Für ChatGPT oder andere Clients wird ein MCP-Client-Bridge (z.B. mcp-proxy) benötigt, um Stdio in SSE/WebSocket zu übersetzen:

npx mcp-proxy node /absoluter/pfad/zu/buchhaltungsbutler-mcp/dist/index.js

Verfügbare Tools

• Belege: list_receipts, get_receipt, create_receipt, upload_receipt, delete_receipt
• Transaktionen: list_transactions, get_transaction, create_transaction, assign_receipt_to_transaction, unassign_receipt_from_transaction
• Rechnungen: create_invoice, create_invoice_draft
• Buchungen: list_postings, create_free_posting
• Stammdaten: list_debtors, list_creditors, list_posting_accounts, create_debtor, create_creditor
• Sonstiges: list_accounts, add_comment, list_cost_locations, create_cost_location

Die vollständige API-Dokumentation liegt als api-spec.json im Projekt und kann mit den offiziellen BuchhaltungsButler API-Docs abgeglichen werden.

Sicherheit

• API Client und Secret sind vertraulich. Speichere sie nicht im Repository, sondern nur in der Claude-Desktop-Konfiguration oder in Umgebungsvariablen.
• Die .gitignore schließt node_modules/, dist/ und .env aus.

Entwicklung

npm run dev     # TypeScript im Watch-Modus
npm run build   # Einmalig bauen
npm start       # Server starten

Lizenz

MIT