buchpilot-mcp

BuchPilot MCP Server

MCP Server für DACH-Buchhaltung — Kontakte, Rechnungen, Belege und Angebote direkt aus Claude, Cursor oder jedem MCP-kompatiblen Client verwalten.

Was ist das?

BuchPilot MCP ist ein Model Context Protocol Server, der dein Buchhaltungssystem (aktuell Lexoffice) mit KI-Assistenten verbindet. Du kannst per natürlicher Sprache Rechnungen erstellen, Kontakte verwalten und überfällige Zahlungen prüfen — direkt in Claude Desktop, Cursor oder jedem anderen MCP-Client.

Features

• 15 Tools für vollständige Buchhaltungs-Automatisierung
• Kontakte erstellen, abrufen, auflisten, aktualisieren
• Rechnungen erstellen, abrufen, auflisten, aktualisieren, PDF herunterladen
• Belege erstellen, abrufen, auflisten (Eingangsrechnungen, Gutschriften)
• Angebote erstellen, abrufen
• Überfällige Rechnungen mit Beträgen und Tagen überfällig
• Backend-Architektur — aktuell Lexoffice, erweiterbar für sevDesk, Billomat etc.
• Plugin-fähig — kann E-Invoice MCP Tools integrieren (einvoice-mcp)
• Keine Datenbank, kein State — reiner API-Proxy

Installation

Voraussetzungen

• Node.js >= 18
• Ein Lexoffice-Account mit API-Key

npm (global)

npm install -g buchpilot-mcp

Von Source

git clone https://github.com/makririch/buchpilot-mcp.git
cd buchpilot-mcp
npm install
npm run build

Konfiguration

Erstelle eine Konfigurationsdatei .buchpilot.json an einem der folgenden Orte:

• Pfad aus Umgebungsvariable BUCHPILOT_CONFIG
• ~/.buchpilot.json (Home-Verzeichnis)
• ./.buchpilot.json (aktuelles Verzeichnis)

Inhalt der .buchpilot.json

{
  "backends": {
    "lexoffice": {
      "api_key": "DEIN_LEXOFFICE_API_KEY"
    }
  },
  "default_backend": "lexoffice"
}

Lexoffice API-Key erstellen

• Gehe zu Lexoffice Public API
• Klicke auf API-Key erstellen
• Kopiere den Key und füge ihn in .buchpilot.json ein

Sicherheitshinweis: Speichere den API-Key nie in Git. Füge .buchpilot.json zu deiner .gitignore hinzu.

Nutzung

Server starten (standalone)

# Nach npm install -g:
buchpilot-mcp

# Oder von Source:
npm start

# Entwicklung mit Auto-Reload:
npm run dev

Der Server läuft über stdio und wartet auf MCP-Nachrichten.

In Claude Desktop verwenden

Siehe Claude Desktop Setup Guide für eine detaillierte Anleitung.

Kurzversion — füge in claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "buchpilot": {
      "command": "npx",
      "args": ["-y", "buchpilot-mcp"],
      "env": {
        "BUCHPILOT_CONFIG": "/Users/DEIN_NAME/.buchpilot.json"
      }
    }
  }
}

Beispiele (natürliche Sprache in Claude)

Nachdem du den Server konfiguriert hast, kannst du Claude z.B. fragen:

• "Erstelle einen Kontakt für die Firma Beispiel GmbH mit der E-Mail [e-mail]"
• "Zeige mir alle offenen Rechnungen"
• "Erstelle eine Rechnung an Kontakt XYZ: 10 Stunden Beratung zu je 150 EUR"
• "Welche Rechnungen sind überfällig?"
• "Lade die PDF von Rechnung ABC herunter"
• "Erstelle ein Angebot für 5 Lizenzen a 49 EUR/Monat"

Tool-Referenz

Eine vollständige Referenz aller 15 Tools mit Parametern, Beispiel-Inputs und Beispiel-Outputs findest du in docs/tool-reference.md.

Kurzübersicht

Tool	Beschreibung
create_contact	Neuen Kontakt anlegen (Person oder Firma)
get_contact	Kontakt per ID abrufen
list_contacts	Kontakte auflisten mit Filtern
update_contact	Kontakt aktualisieren
create_invoice	Neue Rechnung mit Positionen erstellen
get_invoice	Rechnung per ID abrufen
list_invoices	Rechnungen auflisten (nach Status filterbar)
get_invoice_pdf	Rechnung als PDF herunterladen (Base64)
update_invoice	Entwurfs-Rechnung aktualisieren
create_voucher	Neuen Beleg anlegen
get_voucher	Beleg per ID abrufen
list_vouchers	Belege auflisten
create_quotation	Neues Angebot mit Positionen erstellen
get_quotation	Angebot per ID abrufen
get_overdue_invoices	Überfällige Rechnungen mit Analyse

E-Invoice Integration

BuchPilot MCP kann optional das E-Invoice MCP Paket integrieren, um XRechnung und ZUGFeRD direkt aus dem Buchhaltungssystem zu erzeugen:

// In deinem eigenen MCP-Server:
import { registerEInvoiceTools } from "einvoice-mcp";
registerEInvoiceTools(server);
// Ergebnis: 15 + 4 = 19 Tools

FAQ / Troubleshooting

"No .buchpilot.json found"

Der Server findet keine Konfigurationsdatei. Erstelle eine .buchpilot.json in deinem Home-Verzeichnis:

echo '{"backends":{"lexoffice":{"api_key":"DEIN_KEY"}},"default_backend":"lexoffice"}' > ~/.buchpilot.json

"401 Unauthorized" bei Lexoffice

• Ist der API-Key korrekt in .dachflow.json?
• Ist der Key noch aktiv? Prüfe unter Lexoffice Public API
• API-Keys können ablaufen — erstelle ggf. einen neuen

"429 Too Many Requests"

Lexoffice erlaubt max. 2 Requests pro Sekunde. Wenn du viele Operationen hintereinander ausführst, warte kurz zwischen den Anfragen.

Server startet, aber Claude erkennt die Tools nicht

• Prüfe ob die claude_desktop_config.json korrekt ist
• Starte Claude Desktop neu nach Konfigurationsänderungen
• Prüfe die Logs: ~/Library/Logs/Claude/mcp.log (macOS)

Rechnung kann nicht aktualisiert werden

Nur Rechnungen im Status draft (Entwurf) können aktualisiert werden. Finalisierte Rechnungen sind unveränderlich.

Backend "sevDesk" nicht verfügbar

Aktuell wird nur Lexoffice als Backend unterstützt. sevDesk-Unterstützung ist geplant. Du kannst die n8n-Nodes (n8n-nodes-buchpilot) für sevDesk verwenden.

Lizenz

MIT — Frei nutzbar, auch kommerziell.

Autor

MaKri — GitHub