{
  "markdown": "# BuchPilot MCP Server\n\n> MCP Server fuer DACH-Buchhaltung — Kontakte, Rechnungen, Belege und Angebote direkt aus Claude, Cursor oder jedem MCP-kompatiblen Client verwalten.\n\n[![npm version](https://img.shields.io/npm/v/buchpilot-mcp.svg)](https://www.npmjs.com/package/buchpilot-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n## Was ist das?\n\nBuchPilot MCP ist ein [Model Context Protocol](https://modelcontextprotocol.io/) 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.\n\n## Features\n\n- **15 Tools** fuer vollstaendige Buchhaltungs-Automatisierung\n- **Kontakte** erstellen, abrufen, auflisten, aktualisieren\n- **Rechnungen** erstellen, abrufen, auflisten, aktualisieren, PDF herunterladen\n- **Belege** erstellen, abrufen, auflisten (Eingangsrechnungen, Gutschriften)\n- **Angebote** erstellen, abrufen\n- **Ueberfaellige Rechnungen** mit Betraegen und Tagen ueberfaellig\n- **Backend-Architektur** — aktuell Lexoffice, erweiterbar fuer sevDesk, Billomat etc.\n- **Plugin-faehig** — kann E-Invoice MCP Tools integrieren (`einvoice-mcp`)\n- Keine Datenbank, kein State — reiner API-Proxy\n\n## Installation\n\n### Voraussetzungen\n\n- Node.js >= 18\n- Ein [Lexoffice](https://www.lexoffice.de/)-Account mit API-Key\n\n### npm (global)\n\n```bash\nnpm install -g buchpilot-mcp\n```\n\n### Von Source\n\n```bash\ngit clone https://github.com/makririch/buchpilot-mcp.git\ncd buchpilot-mcp\nnpm install\nnpm run build\n```\n\n## Konfiguration\n\nErstelle eine Konfigurationsdatei `.buchpilot.json` an einem der folgenden Orte:\n\n1. Pfad aus Umgebungsvariable `BUCHPILOT_CONFIG`\n2. `~/.buchpilot.json` (Home-Verzeichnis)\n3. `./.buchpilot.json` (aktuelles Verzeichnis)\n\n### Inhalt der .buchpilot.json\n\n```json\n{\n  \"backends\": {\n    \"lexoffice\": {\n      \"api_key\": \"DEIN_LEXOFFICE_API_KEY\"\n    }\n  },\n  \"default_backend\": \"lexoffice\"\n}\n```\n\n### Lexoffice API-Key erstellen\n\n1. Gehe zu [Lexoffice Public API](https://app.lexoffice.de/addons/public-api)\n2. Klicke auf **API-Key erstellen**\n3. Kopiere den Key und fuege ihn in `.buchpilot.json` ein\n\n> **Sicherheitshinweis:** Speichere den API-Key nie in Git. Fuege `.buchpilot.json` zu deiner `.gitignore` hinzu.\n\n## Nutzung\n\n### Server starten (standalone)\n\n```bash\n# Nach npm install -g:\nbuchpilot-mcp\n\n# Oder von Source:\nnpm start\n\n# Entwicklung mit Auto-Reload:\nnpm run dev\n```\n\nDer Server laeuft ueber stdio und wartet auf MCP-Nachrichten.\n\n### In Claude Desktop verwenden\n\nSiehe [Claude Desktop Setup Guide](docs/claude-desktop-setup.md) fuer eine detaillierte Anleitung.\n\nKurzversion — fuege in `claude_desktop_config.json` hinzu:\n\n```json\n{\n  \"mcpServers\": {\n    \"buchpilot\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"buchpilot-mcp\"],\n      \"env\": {\n        \"BUCHPILOT_CONFIG\": \"/Users/DEIN_NAME/.buchpilot.json\"\n      }\n    }\n  }\n}\n```\n\n### Beispiele (natuerliche Sprache in Claude)\n\nNachdem du den Server konfiguriert hast, kannst du Claude z.B. fragen:\n\n- \"Erstelle einen Kontakt fuer die Firma Beispiel GmbH mit der E-Mail info@beispiel.de\"\n- \"Zeige mir alle offenen Rechnungen\"\n- \"Erstelle eine Rechnung an Kontakt XYZ: 10 Stunden Beratung zu je 150 EUR\"\n- \"Welche Rechnungen sind ueberfaellig?\"\n- \"Lade die PDF von Rechnung ABC herunter\"\n- \"Erstelle ein Angebot fuer 5 Lizenzen a 49 EUR/Monat\"\n\n## Tool-Referenz\n\nEine vollstaendige Referenz aller 15 Tools mit Parametern, Beispiel-Inputs und Beispiel-Outputs findest du in [docs/tool-reference.md](docs/tool-reference.md).\n\n### Kurzuebersicht\n\n| Tool | Beschreibung |\n|------|-------------|\n| `create_contact` | Neuen Kontakt anlegen (Person oder Firma) |\n| `get_contact` | Kontakt per ID abrufen |\n| `list_contacts` | Kontakte auflisten mit Filtern |\n| `update_contact` | Kontakt aktualisieren |\n| `create_invoice` | Neue Rechnung mit Positionen erstellen |\n| `get_invoice` | Rechnung per ID abrufen |\n| `list_invoices` | Rechnungen auflisten (nach Status filterbar) |\n| `get_invoice_pdf` | Rechnung als PDF herunterladen (Base64) |\n| `update_invoice` | Entwurfs-Rechnung aktualisieren |\n| `create_voucher` | Neuen Beleg anlegen |\n| `get_voucher` | Beleg per ID abrufen |\n| `list_vouchers` | Belege auflisten |\n| `create_quotation` | Neues Angebot mit Positionen erstellen |\n| `get_quotation` | Angebot per ID abrufen |\n| `get_overdue_invoices` | Ueberfaellige Rechnungen mit Analyse |\n\n## E-Invoice Integration\n\nBuchPilot MCP kann optional das [E-Invoice MCP](https://www.npmjs.com/package/einvoice-mcp) Paket integrieren, um XRechnung und ZUGFeRD direkt aus dem Buchhaltungssystem zu erzeugen:\n\n```typescript\n// In deinem eigenen MCP-Server:\nimport { registerEInvoiceTools } from \"einvoice-mcp\";\nregisterEInvoiceTools(server);\n// Ergebnis: 15 + 4 = 19 Tools\n```\n\n## FAQ / Troubleshooting\n\n### \"No .buchpilot.json found\"\n\nDer Server findet keine Konfigurationsdatei. Erstelle eine `.buchpilot.json` in deinem Home-Verzeichnis:\n\n```bash\necho '{\"backends\":{\"lexoffice\":{\"api_key\":\"DEIN_KEY\"}},\"default_backend\":\"lexoffice\"}' > ~/.buchpilot.json\n```\n\n### \"401 Unauthorized\" bei Lexoffice\n\n- Ist der API-Key korrekt in `.dachflow.json`?\n- Ist der Key noch aktiv? Pruefe unter [Lexoffice Public API](https://app.lexoffice.de/addons/public-api)\n- API-Keys koennen ablaufen — erstelle ggf. einen neuen\n\n### \"429 Too Many Requests\"\n\nLexoffice erlaubt max. 2 Requests pro Sekunde. Wenn du viele Operationen hintereinander ausfuehrst, warte kurz zwischen den Anfragen.\n\n### Server startet, aber Claude erkennt die Tools nicht\n\n- Pruefe ob die `claude_desktop_config.json` korrekt ist\n- Starte Claude Desktop neu nach Konfigurationsaenderungen\n- Pruefe die Logs: `~/Library/Logs/Claude/mcp.log` (macOS)\n\n### Rechnung kann nicht aktualisiert werden\n\nNur Rechnungen im Status **draft** (Entwurf) koennen aktualisiert werden. Finalisierte Rechnungen sind unveraenderlich.\n\n### Backend \"sevDesk\" nicht verfuegbar\n\nAktuell wird nur **Lexoffice** als Backend unterstuetzt. sevDesk-Unterstuetzung ist geplant. Du kannst die n8n-Nodes (`n8n-nodes-buchpilot`) fuer sevDesk verwenden.\n\n## Lizenz\n\nMIT — Frei nutzbar, auch kommerziell.\n\n## Autor\n\n**MaKri** — [GitHub](https://github.com/makririch/buchpilot-mcp)\n",
  "bytes": 6325,
  "sha": "e8263b0270df1ca3cd1c4d59bc28d60560fefa1a1e3063bc9b7806cc6edfd5cd",
  "repo_slug": "makririch/buchpilot-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_makririch_buchpilot_c9b1f855/readme"
}