# BuchPilot MCP Server

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

[![npm version](https://img.shields.io/npm/v/buchpilot-mcp.svg)](https://www.npmjs.com/package/buchpilot-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](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)