io.github.makririch/buchpilot

BuchPilot MCP Server

MCP Server fuer 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 natuerlicher Sprache Rechnungen erstellen, Kontakte verwalten und ueberfaellige Zahlungen pruefen — direkt in Claude Desktop, Cursor oder jedem anderen MCP-Client.

Features

• 15 Tools fuer vollstaendige Buchhaltungs-Automatisierung
• Kontakte erstellen, abrufen, auflisten, aktualisieren
• Rechnungen erstellen, abrufen, auflisten, aktualisieren, PDF herunterladen
• Belege erstellen, abrufen, auflisten (Eingangsrechnungen, Gutschriften)
• Angebote erstellen, abrufen
• Ueberfaellige Rechnungen mit Betraegen und Tagen ueberfaellig
• Backend-Architektur — aktuell Lexoffice, erweiterbar fuer sevDesk, Billomat etc.
• Plugin-faehig — 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 fuege ihn in .buchpilot.json ein

Sicherheitshinweis: Speichere den API-Key nie in Git. Fuege .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 laeuft ueber stdio und wartet auf MCP-Nachrichten.

In Claude Desktop verwenden

Siehe Claude Desktop Setup Guide fuer eine detaillierte Anleitung.

Kurzversion — fuege in claude_desktop_config.json hinzu:

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

Beispiele (natuerliche Sprache in Claude)

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

• "Erstelle einen Kontakt fuer die Firma Beispiel GmbH mit der E-Mail info@beispiel.de"
• "Zeige mir alle offenen Rechnungen"
• "Erstelle eine Rechnung an Kontakt XYZ: 10 Stunden Beratung zu je 150 EUR"
• "Welche Rechnungen sind ueberfaellig?"
• "Lade die PDF von Rechnung ABC herunter"
• "Erstelle ein Angebot fuer 5 Lizenzen a 49 EUR/Monat"

Tool-Referenz

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

Kurzuebersicht

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	Ueberfaellige 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? Pruefe unter Lexoffice Public API
• API-Keys koennen ablaufen — erstelle ggf. einen neuen

"429 Too Many Requests"

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

Server startet, aber Claude erkennt die Tools nicht

• Pruefe ob die claude_desktop_config.json korrekt ist
• Starte Claude Desktop neu nach Konfigurationsaenderungen
• Pruefe die Logs: ~/Library/Logs/Claude/mcp.log (macOS)

Rechnung kann nicht aktualisiert werden

Nur Rechnungen im Status draft (Entwurf) koennen aktualisiert werden. Finalisierte Rechnungen sind unveraenderlich.

Backend "sevDesk" nicht verfuegbar

Aktuell wird nur Lexoffice als Backend unterstuetzt. sevDesk-Unterstuetzung ist geplant. Du kannst die n8n-Nodes (n8n-nodes-buchpilot) fuer sevDesk verwenden.

Lizenz

MIT — Frei nutzbar, auch kommerziell.

Autor

MaKri — GitHub