# BuchhaltungsButler MCP-Server

Ein [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)-Server für die [BuchhaltungsButler API](https://app.buchhaltungsbutler.de/docs/api/v1/). Damit kannst du BuchhaltungsButler direkt aus Claude Desktop, ChatGPT oder jedem anderen MCP-Client heraus nutzen.

## Voraussetzungen

- Node.js ≥ 18
- BuchhaltungsButler API-Zugang (API Client + API Secret + API Key eines Kunden)

## Installation

```bash
git clone <repo-url>
cd buchhaltungsbutler-mcp
npm install
npm run build
```

## Konfiguration

Die folgenden Umgebungsvariablen werden benötigt:

| Variable | Beschreibung |
|----------|-------------|
| `BUCHHALTUNGSBUTLER_API_CLIENT` | Dein API Client |
| `BUCHHALTUNGSBUTLER_API_SECRET` | Dein API Secret |
| `BUCHHALTUNGSBUTLER_API_KEY` | Der API-Key des zu verwaltenden Kunden (kann pro Tool-Aufruf überschrieben werden) |

Optional:

| Variable | Beschreibung |
|----------|-------------|
| `BUCHHALTUNGSBUTLER_API_URL` | Standard: `https://webapp.buchhaltungsbutler.de/api/v1` |

## Verwendung in Claude Desktop

1. Öffne die Claude Desktop Konfiguration:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. Füge den Server hinzu:

```json
{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/absoluter/pfad/zu/buchhaltungsbutler-mcp/dist/index.js"],
      "env": {
        "BUCHHALTUNGSBUTLER_API_CLIENT": "dein-api-client",
        "BUCHHALTUNGSBUTLER_API_SECRET": "dein-api-secret",
        "BUCHHALTUNGSBUTLER_API_KEY": "kunden-api-key"
      }
    }
  }
}
```

3. Claude Desktop neu starten.

## Verwendung in ChatGPT / anderen Clients

Dieser Server verwendet den MCP-Stdio-Transport, der von Claude Desktop nativ unterstützt wird. Für ChatGPT oder andere Clients wird ein MCP-Client-Bridge (z.B. [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy)) benötigt, um Stdio in SSE/WebSocket zu übersetzen:

```bash
npx mcp-proxy node /absoluter/pfad/zu/buchhaltungsbutler-mcp/dist/index.js
```

## Verfügbare Tools

- **Belege**: `list_receipts`, `get_receipt`, `create_receipt`, `upload_receipt`, `delete_receipt`
- **Transaktionen**: `list_transactions`, `get_transaction`, `create_transaction`, `assign_receipt_to_transaction`, `unassign_receipt_from_transaction`
- **Rechnungen**: `create_invoice`, `create_invoice_draft`
- **Buchungen**: `list_postings`, `create_free_posting`
- **Stammdaten**: `list_debtors`, `list_creditors`, `list_posting_accounts`, `create_debtor`, `create_creditor`
- **Sonstiges**: `list_accounts`, `add_comment`, `list_cost_locations`, `create_cost_location`

Die vollständige API-Dokumentation liegt als `api-spec.json` im Projekt und kann mit den offiziellen [BuchhaltungsButler API-Docs](https://app.buchhaltungsbutler.de/docs/api/v1/) abgeglichen werden.

## Sicherheit

- API Client und Secret sind **vertraulich**. Speichere sie nicht im Repository, sondern nur in der Claude-Desktop-Konfiguration oder in Umgebungsvariablen.
- Die `.gitignore` schließt `node_modules/`, `dist/` und `.env` aus.

## Entwicklung

```bash
npm run dev     # TypeScript im Watch-Modus
npm run build   # Einmalig bauen
npm start       # Server starten
```

## Lizenz

MIT