# Buchungslotse: instructions for AI agents

## What Buchungslotse is

Buchungslotse is a bookkeeping portal: upload receipts, book them on real DATEV accounts (SKR03/SKR04) following the tax advisor's rules, and export to DATEV without rework.

## Get access

- Request access via the waitlist at https://buchungslotse-dev-landing.acatron-local.de/#zugang (closed beta).
- Once the user has an account: the company admin opens the portal, goes to Settings, "Agenten-Zugang", and creates a token. The profile "Buchhaltung" is recommended. The token is shown once and is valid for 90 days by default.

## Connect

- MCP server URL: https://buchungslotse-dev-api.acatron-local.de/api/_mcp
- Transport: Streamable HTTP
- Header: Authorization: Bearer <token>

Claude Code:

```bash
claude mcp add --transport http buchungslotse https://buchungslotse-dev-api.acatron-local.de/api/_mcp --header "Authorization: Bearer <token>"
```

Cursor (mcpServers block in .cursor/mcp.json):

```json
{
  "mcpServers": {
    "buchungslotse": {
      "url": "https://buchungslotse-dev-api.acatron-local.de/api/_mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

Chat assistants in the browser that only support OAuth cannot connect yet.

## What you can do

Upload and analyse receipts, create bookings, allocate payments, manage standing orders, read the trial balance, preview the VAT return and create posting rules. The exact tool names are discovered via the server's tool list. The available tools depend on the token profile; writing requires a profile with write permission.

Files (receipts, imports) are not transferred via MCP, but via HTTP: POST https://buchungslotse-dev-api.acatron-local.de/api/file-assets/upload with the header "Authorization: Bearer <token>", for example: curl -H "Authorization: Bearer <token>" -F file=@receipt.pdf https://buchungslotse-dev-api.acatron-local.de/api/file-assets/upload

## Rules

- Ask the user before posting anything that is ambiguous (private vs. business, missing purpose of a receipt).
- Never send invoices without explicit confirmation.
- Every action is logged and can be reversed.
- Do not guess accounts, follow the posting rules.

## Deutsch

### Was Buchungslotse ist

Buchungslotse ist ein Buchhaltungsportal: Belege hochladen, auf echten DATEV-Konten (SKR03/SKR04) nach den Regeln des Steuerberaters buchen und ohne Nacharbeit nach DATEV exportieren.

### Zugang bekommen

- Zugang über die Warteliste anfragen: https://buchungslotse-dev-landing.acatron-local.de/#zugang (geschlossene Beta).
- Sobald die Nutzerin oder der Nutzer ein Konto hat: Die Firmen-Admin öffnet das Portal, geht zu Einstellungen, "Agenten-Zugang", und legt ein Token an. Das Profil "Buchhaltung" wird empfohlen. Das Token wird nur einmal angezeigt und ist standardmäßig 90 Tage gültig.

### Verbinden

- MCP-Server-Adresse: https://buchungslotse-dev-api.acatron-local.de/api/_mcp
- Transport: Streamable HTTP
- Header: Authorization: Bearer <token>

Claude Code:

```bash
claude mcp add --transport http buchungslotse https://buchungslotse-dev-api.acatron-local.de/api/_mcp --header "Authorization: Bearer <token>"
```

Cursor (mcpServers-Block in .cursor/mcp.json):

```json
{
  "mcpServers": {
    "buchungslotse": {
      "url": "https://buchungslotse-dev-api.acatron-local.de/api/_mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

Chat-Assistenten im Browser, die nur OAuth unterstützen, können sich noch nicht verbinden.

### Was du tun kannst

Belege hochladen und analysieren, Buchungen anlegen, Zahlungen zuordnen, Daueraufträge verwalten, die Summen- und Saldenliste lesen, die Umsatzsteuer-Voranmeldung als Vorschau abrufen und Buchungsregeln anlegen. Die genauen Tool-Namen stehen in der Tool-Liste des Servers. Welche Tools verfügbar sind, hängt vom Token-Profil ab; Schreiben braucht ein Profil mit Schreibrecht.

Dateien (Belege, Importe) werden nicht per MCP übertragen, sondern per HTTP: POST https://buchungslotse-dev-api.acatron-local.de/api/file-assets/upload mit dem Header "Authorization: Bearer <token>", zum Beispiel: curl -H "Authorization: Bearer <token>" -F file=@beleg.pdf https://buchungslotse-dev-api.acatron-local.de/api/file-assets/upload

### Regeln

- Frage vor dem Buchen nach, wenn etwas unklar ist (privat oder geschäftlich, fehlender Zweck eines Belegs).
- Sende Rechnungen nie ohne ausdrückliche Bestätigung.
- Jede Aktion wird protokolliert und kann rückgängig gemacht werden.
- Rate keine Konten, folge den Buchungsregeln.
