Buchhaltungsbutler-MCP

# ohneben's Buchhaltungsbutler MCP

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-ohneben-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/ohneben)

---

#### Lizenz & Checks

[![CI](https://github.com/ohneben/Buchhaltungsbutler-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/ohneben/Buchhaltungsbutler-MCP/actions/workflows/ci.yml)
[![Lizenz: MIT](https://img.shields.io/badge/Lizenz-MIT-green.svg)](./LICENSE.md)

#### MCP-Register

[![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0.1%2Fservers%2Fio.github.ohneben%252Fbuchhaltungsbutler-mcp%2Fversions%2Flatest&query=%24.server.version&prefix=v&label=MCP%20Registry&color=blue&logo=modelcontextprotocol&logoColor=white)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ohneben%2Fbuchhaltungsbutler-mcp/versions/latest)
[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/ohneben/buchhaltungsbutler-mcp)
[![Buchhaltungsbutler-MCP MCP server](https://glama.ai/mcp/servers/ohneben/Buchhaltungsbutler-MCP/badges/score.svg)](https://glama.ai/mcp/servers/ohneben/Buchhaltungsbutler-MCP)

Verwalte deine [BuchhaltungsButler](https://www.buchhaltungsbutler.de/)-Buchhaltung in
natürlicher Sprache aus KI-Assistenten wie **Claude**, **Cursor** und jedem anderen
[MCP](https://modelcontextprotocol.io)-Client.

Dieser [Model-Context-Protocol](https://modelcontextprotocol.io)-Server stellt die
**[BuchhaltungsButler API v1](https://app.buchhaltungsbutler.de/docs/api/v1/)** bereit —
alle **54 Endpunkte**, automatisch aus der offiziellen OpenAPI-Spezifikation
(Spec-Version **1.9.1**) als MCP-Tools generiert. Jedes Tool ist
**sicherheitskategorisiert** (nur lesend / schreibend / destruktiv), damit dein Assistent
weiß, was eine Aktion tut, *bevor* er sie ausführt. Läuft über **stdio**
(Claude Desktop und andere lokale Launcher) oder **Streamable HTTP** (gehostet in Docker).

## Warum dieser Server

Manche MCP-Server leiten eine API einfach nur weiter. Dieser hier ist darauf ausgelegt,
**gefahrlos an ein Sprachmodell übergeben** und **im Alltag betrieben** werden zu können:

| Was du bekommst | Warum das zählt |
| --- | --- |
| **Alle 54 Endpunkte, automatisch generiert** aus der offiziellen Spec | Vollständige Abdeckung von Belegen, Transaktionen, Buchungen, Rechnungen, Auswertungen und Stammdaten — nichts handverlesen, nichts vergessen. |
| **Jedes Tool ist sicherheitskategorisiert** 🟢 / 🟡 / 🔴 | Ein Banner am Anfang jeder Tool-Beschreibung sagt dem Modell genau, was passiert — lesen, anlegen, ändern, zurücknehmen oder löschen — bevor es handelt. |
| **Maschinenlesbare MCP-Annotationen** (`readOnlyHint`, `destructiveHint`) | Hosts, die Annotationen auswerten (Claude gehört dazu), können Lesezugriffe automatisch zulassen und vor destruktiven Aktionen eine Bestätigung verlangen. |
| **Zwei Transporte: stdio *und* Streamable HTTP** | Lokal in Claude Desktop nutzen — oder einen dauerhaft laufenden Server betreiben, den beliebig viele MCP-Clients über HTTP erreichen. |
| **Docker + docker-compose, Health-Check, Auto-Restart** | Produktionsnahes Deployment ab Werk: `docker compose up`, und er bleibt oben. |
| **Bearer-Token-Authentifizierung** am HTTP-Endpunkt | Pflicht, sobald der Server über Loopback hinaus gebunden ist: ohne `MCP_AUTH_TOKEN` verweigert er den Start, statt die API ungeschützt bereitzustellen. |
| **Eingebautes Rate-Limiting** | Drosselt sich selbst unter dem BuchhaltungsButler-Limit von 100 Anfragen/Kunde/Minute, damit du nie dagegenläufst. |
| **Deine Zugangsdaten erreichen das Modell nie** | Die Credentials liegen in der Server-Umgebung und werden pro Anfrage injiziert — der Assistent sieht nur Tool-Eingaben und API-Antworten. |

### Im Vergleich

Nach aktuellem Stand ist dies der einzige dedizierte BuchhaltungsButler-MCP-Server.
Alternativ *könntest* du einen generischen OpenAPI→MCP-Wrapper auf die Spec richten —
das lässt allerdings einiges liegen:

| Fähigkeit | **Dieses Projekt** | Generischer OpenAPI→MCP-Wrapper\* |
| --- | :---: | :---: |
| Alle 54 BuchhaltungsButler-Endpunkte als Tools | ✅ | ✅ |
| 🟢 / 🟡 / 🔴 Sicherheitskategorie + Banner pro Tool | ✅ | ❌ |
| `readOnlyHint` / `destructiveHint` MCP-Annotationen | ✅ | ➖ |
| `$ref`-Auflösung für Batch-Payloads + HTML-bereinigte Beschreibungen | ✅ | ➖ |
| Eingebautes Rate-Limiting (bleibt unter BBs 100/Kunde/Min.) | ✅ | ❌ |
| `stdio`-Transport | ✅ | ✅ |
| **Streamable-HTTP-Transport** | ✅ | ➖ |
| **Docker + docker-compose**, Health-Check, Auto-Restart | ✅ | ❌ |
| **Erzwungene Bearer-Token-Auth** am Endpunkt | ✅ | ❌ |
| Credentials serverseitig injiziert, nie ans Modell gesendet | ✅ | ➖ |
| Lizenz | MIT | unterschiedlich |

<sub>\*Generische OpenAPI→MCP-Wrapper machen aus jeder Swagger-/OpenAPI-Spec MCP-Tools.
Sie erreichen dieselben Endpunkte, behandeln aber jede Operation gleich — keine
Sicherheitskategorien, keine Betriebsgeschichte, keine auf echte Buchhaltungsdaten
abgestimmten Leitplanken. „➖“ = je nach Werkzeug unterschiedlich / nicht garantiert.</sub>

## Was du damit machen kannst

Sobald der Server verbunden ist, kannst du deinen Assistenten zum Beispiel bitten:

- „Liste alle Eingangsbelege vom letzten Monat auf, die noch offen sind.“
- „Erstelle einen Rechnungsentwurf für die ACME GmbH: 10 Stunden Beratung à 120 €.“
- „Buche diese Banktransaktion auf Sachkonto 4400.“
- „Lade diesen PDF-Beleg hoch und ordne ihn der passenden Transaktion zu.“
- „Zeig mir meine Kreditoren und leg einen neuen für unseren Hosting-Anbieter an.“
- „Erstelle mir die BWA für das letzte Quartal und zeig mir das Kontenblatt zu Konto 4400.“

Die Tools werden automatisch aus der offiziellen API generiert und in 🟢 nur lesend,
🟡 schreibend und 🔴 destruktiv gruppiert — ein gut umgesetzter Host kann jede Gruppe
unterschiedlich behandeln.

## Funktionsweise

```
Claude / Cursor / beliebiger MCP-Client  ──MCP──►  dieser Server  ──HTTPS──►  BuchhaltungsButler API (Cloud)
```

Der Server liest die mitgelieferte OpenAPI-Spec ein und macht daraus MCP-Tools (inklusive
Auflösung von `$ref`-Batch-Payloads und Entfernen von HTML aus den Beschreibungen),
versieht jedes Tool mit seiner Sicherheitskategorie und hängt deine Basic-Auth-Credentials
sowie den `api_key` an jede ausgehende Anfrage. Deine Zugangsdaten bleiben in der
Server-Umgebung — das Modell sieht sie nie und fasst sie nie an.

## Voraussetzungen

- Ein **BuchhaltungsButler-Konto mit API-Zugang** — ein **API Client + API Secret**
  (Einstellungen → API) sowie ein Kunden-**`api_key`**
  (siehe [API-Zugangsdaten besorgen](#api-zugangsdaten-besorgen)).
- **Docker** (Docker Desktop unter macOS/Windows) für den Schnellstart unten — oder
  **Node.js ≥ 18**, um [aus dem Quellcode zu starten](#aus-dem-quellcode-starten-stdio-ohne-docker).

## Schnellstart (Docker)

**1. Zugangsdaten hinterlegen.** Beispielkonfiguration kopieren und ausfüllen:

```bash
cp .env.example .env
# .env bearbeiten → BB_API_CLIENT, BB_API_SECRET, BB_API_KEY setzen
#                 → MCP_AUTH_TOKEN setzen. PFLICHT, sonst startet der Server
#                   nicht, denn .env.example bindet auf 0.0.0.0:
#                   openssl rand -hex 32
```

**2. Server starten:**

```bash
docker compose up -d --build
```

**3. Prüfen, ob er läuft:**

```bash
curl -s http://localhost:3000/health     # → {"status":"ok","server":"buchhaltungsbutler-mcp"}
```

**4. MCP-Client verbinden.** Entfernte Endpunkte werden in Claude als **Custom Connector**
hinzugefügt (Einstellungen → Connectors) oder lokal mit
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) gebrückt. Trage Folgendes unter
`mcpServers` in deiner Client-Konfiguration ein und starte die App danach vollständig neu:

```json
{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/mcp",
        "--header", "Authorization: Bearer DEIN_MCP_AUTH_TOKEN"
      ]
    }
  }
}
```

(Die `--header`-Zeile entfällt nur, wenn du ohne Token auf Loopback bindest.
Im Docker-Schnellstart oben ist das Token Pflicht.)

### Lieber ein fertiges Image?

Jeder Push auf `main` veröffentlicht ein startbereites Image in der GitHub Container
Registry — damit kannst du den lokalen Build komplett überspringen:

```bash
docker run -d --name buchhaltungsbutler-mcp -p 3000:3000 --env-file .env \
  ghcr.io/ohneben/buchhaltungsbutler-mcp:latest
```

## API-Zugangsdaten besorgen

BuchhaltungsButler nutzt zwei Authentifizierungsebenen (siehe die
[offizielle Dokumentation](https://app.buchhaltungsbutler.de/docs/api/v1/)):

1. **HTTP-Basic-Auth** — ein **API Client** + **API Secret**, deine globalen
   API-Zugangsdaten. Zu finden bzw. anzulegen in BuchhaltungsButler unter
   **Einstellungen → API**.
2. **`api_key`** — legt fest, *auf welches Kundenkonto* sich eine Anfrage bezieht. Er
   steht in den Firmendaten-Einstellungen des jeweiligen Kunden.

Trage alle drei Werte in `.env` ein. Der Server hängt sie an jede Anfrage an, dein
Assistent bekommt sie also nie zu sehen. Ein einzelner Tool-Aufruf kann optional einen
eigenen `api_key` mitgeben, um ein anderes Kundenkonto anzusprechen.

## Konfiguration

Alles wird in `.env` gesetzt (kopiert aus `.env.example`):

| Variable | Pflicht | Standard | Beschreibung |
|---|---|---|---|
| `BB_API_CLIENT` | ✅ | — | API Client (Basic-Auth-Benutzername) |
| `BB_API_SECRET` | ✅ | — | API Secret (Basic-Auth-Passwort) |
| `BB_API_KEY` | ✅ | — | Standard-Kunden-`api_key` |
| `MCP_TRANSPORT` | — | `stdio` | `stdio` oder `http` (das Docker-Image nutzt standardmäßig `http`) |
| `PORT` | — | `3000` | HTTP-Port, auf dem gelauscht wird |
| `HOST` | — | `0.0.0.0` | HTTP-Bind-Adresse |
| `MCP_HTTP_PATH` | — | `/mcp` | HTTP-Route für MCP |
| `MCP_AUTH_TOKEN` | ⚠️ | _(aus)_ | Verlangt `Authorization: Bearer <Token>` auf `/mcp`. **Pflicht**, wenn `HOST` keine Loopback-Adresse ist — sonst startet der Server