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:

1. Pfad aus Umgebungsvariable BUCHPILOT_CONFIG
2. ~/.buchpilot.json (Home-Verzeichnis)
3. ./.buchpilot.json (aktuelles Verzeichnis)

Inhalt der .buchpilot.json

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

Lexoffice API-Key erstellen

1. Gehe zu Lexoffice Public API
2. Klicke auf API-Key erstellen
3. 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 [email protected]"
• "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