io.github.makririch/buchpilot
DACH accounting for AI: connect sevDesk & Lexoffice to create invoices, contacts, vouchers.
Open source Open in the app JSON README (API)
About
DACH accounting for AI: connect sevDesk & Lexoffice to create invoices, contacts, vouchers.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- makririch
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.2
- Last push
- 2026-04-13T14:55:53Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-29 04:00:27
- Updated
- 2026-08-29 04:00:27
- Origin id
io.github.makririch/buchpilot
README
# BuchPilot MCP Server
> MCP Server fuer DACH-Buchhaltung — Kontakte, Rechnungen, Belege und Angebote direkt aus Claude, Cursor oder jedem MCP-kompatiblen Client verwalten.
[](https://www.npmjs.com/package/buchpilot-mcp)
[](LICENSE)
## Was ist das?
BuchPilot 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.
## 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](https://www.lexoffice.de/)-Account mit API-Key
### npm (global)
```bash
npm install -g buchpilot-mcp
```
### Von Source
```bash
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
```json
{
"backends": {
"lexoffice": {
"api_key": "DEIN_LEXOFFICE_API_KEY"
}
},
"default_backend": "lexoffice"
}
```
### Lexoffice API-Key erstellen
1. Gehe zu [Lexoffice Public API](https://app.lexoffice.de/addons/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)
```bash
# 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](docs/claude-desktop-setup.md) fuer eine detaillierte Anleitung.
Kurzversion — fuege in `claude_desktop_config.json` hinzu:
```json
{
"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](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](https://www.npmjs.com/package/einvoice-mcp) Paket integrieren, um XRechnung und ZUGFeRD direkt aus dem Buchhaltungssystem zu erzeugen:
```typescript
// 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:
```bash
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](https://app.lexoffice.de/addons/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](https://github.com/makririch/buchpilot-mcp)