MCP-Server: Ledgerpilot in Claude und ChatGPT

1Überblick#

Das Model Context Protocol (MCP) ist ein offener Standard, über den KI-Assistenten auf fremde Dienste zugreifen. Ledgerpilot stellt dafür einen Server bereit. Ist er in Claude oder ChatGPT eingerichtet, kann der Assistent auf deine Bitte hin deine Berichte auflisten, ihren Stand prüfen, die Kennzahlen des DATEV-Buchungsstapels abfragen und bei gekauften Berichten Buchungszeilen und Dateien abrufen; Fragen zu deinen Berichten beantwortet die Ledgerpilot-Frageleiste. Auf deine Bitte ruft er außerdem die angebundene Quelle eines Berichts neu ab.

Diese Seite beschreibt die Verbindung, die Anmeldung, alle Werkzeuge mit Parametern und die Regeln, nach denen der Server antwortet.

1.1Verbindungsadresse#

Der Server ist unter genau einer Adresse erreichbar. Sie wird im Assistenten als Connector eingetragen:

Der Endpunkt spricht MCP über Streamable HTTP. Jede Anfrage ist in sich abgeschlossen (zustandslos), die Antworten kommen als JSON, ohne Ereignis-Stream.

1.2Was der Assistent darf#

• deine Berichte und ihren Stand sehen
• Kennzahlen und Gegenprobe abfragen
• Buchungen und Dateien deiner gekauften Berichte abrufen
• der Ledgerpilot-Frageleiste Fragen zu deinen Berichten stellen
• die Daten eines Berichts aktualisieren; dabei entsteht ein neuer Bericht, der bisherige bleibt unverändert

2Verbinden#

Die Verbindung richtest du einmal ein; das dauert etwa eine Minute. Du brauchst dafür ein Ledgerpilot-Konto und die Adresse aus Abschnitt 1.1.

2.1Claude#

1. In Claude Einstellungen → Connectors öffnen.
2. Eigenen Connector hinzufügen wählen, einen Namen vergeben (z. B. „Ledgerpilot“) und https://www.ledgerpilot.io/mcp als Adresse einfügen.
3. Auf Verbinden klicken. Es öffnet sich ein Ledgerpilot-Fenster zur Anmeldung und Zustimmung (Abschnitt 2.3).

In Claude Code trägst du den Server im Terminal ein:

claude mcp add --transport http ledgerpilot https://www.ledgerpilot.io/mcp

Danach in Claude Code /mcp aufrufen, Ledgerpilot wählen und die Anmeldung starten. Das Ledgerpilot-Fenster öffnet sich im Browser; nach dem Erlauben geht es zurück an Claude Code auf deinem Rechner (localhost).

2.2ChatGPT#

1. In ChatGPT Einstellungen → Apps und Connectors öffnen.
2. Unter den erweiterten Einstellungen den Entwicklermodus einschalten.
3. Einen neuen Connector anlegen, https://www.ledgerpilot.io/mcp als Adresse eintragen und OAuth als Anmeldung wählen.
4. Verbinden; es öffnet sich das Ledgerpilot-Fenster zur Anmeldung und Zustimmung.

2.3Anmeldung (OAuth 2.1)#

Der Assistent meldet sich über den Ledgerpilot-eigenen Anmeldedienst an, ohne Drittanbieter. Das Verfahren ist OAuth 2.1 mit Autorisierungscode und PKCE; als Prüfverfahren ist nur S256 zugelassen. Der Assistent registriert sich dabei selbst über dynamische Client-Registrierung (RFC 7591).

1. Der Assistent ruft die Metadaten ab (Abschnitt 2.4) und registriert sich unter /oauth/register.
2. Er öffnet /oauth/authorize. Bist du nicht angemeldet, meldest du dich wie gewohnt bei Ledgerpilot an (Magic-Link, Google oder Apple).
3. Die Zustimmungsseite nennt den Assistenten, die Adresse, an die er zurückleitet, was er darf und mit welchem Ledgerpilot-Konto du verbindest; über „Mit anderem Konto anmelden“ wechselst du es. Leitet der Assistent an deinen eigenen Rechner zurück (Claude Code), weist die Seite darauf hin. Mit „Erlauben“ entsteht die Verbindung; „Abbrechen“ führt mit access_denied zurück.
4. Der Assistent tauscht den Code unter /oauth/token gegen einen Zugangsschlüssel und einen Erneuerungsschlüssel.

2.4Metadaten-Adressen#

Beide Metadaten-Dokumente sind öffentlich abrufbar. Der Assistent findet darüber den Anmeldedienst und seine Endpunkte; für eine eigene Prüfung genügt ein einfacher GET.

GET /.well-known/oauth-protected-resource/mcp HTTP/1.1
Host: www.ledgerpilot.io

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resource": "https://www.ledgerpilot.io/mcp",
  "authorization_servers": ["https://www.ledgerpilot.io/"],
  "scopes_supported": ["berichte:lesen", "dateien:lesen", "daten:aktualisieren"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Ledgerpilot"
}

GET /.well-known/oauth-authorization-server HTTP/1.1
Host: www.ledgerpilot.io

HTTP/1.1 200 OK
Content-Type: application/json

{
  "issuer": "https://www.ledgerpilot.io/",
  "authorization_endpoint": "https://www.ledgerpilot.io/oauth/authorize",
  "token_endpoint": "https://www.ledgerpilot.io/oauth/token",
  "registration_endpoint": "https://www.ledgerpilot.io/oauth/register",
  "revocation_endpoint": "https://www.ledgerpilot.io/oauth/revoke",
  "scopes_supported": ["berichte:lesen", "dateien:lesen", "daten:aktualisieren"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["client_secret_post", "client_secret_basic", "none"],
  "code_challenge_methods_supported": ["S256"],
  …
}

/.well-known/oauth-protected-resource antwortet auch ohne den Anhang /mcp.

2.5Laufzeiten und Trennen#

3Werkzeuge#

Der Server stellt sieben Werkzeuge bereit. Sechs sind als nur lesend gekennzeichnet (readOnlyHint: true); daten_aktualisieren trägt readOnlyHint: false, weil es einen neuen Bericht anlegt. Welcher Kunde fragt, ergibt sich allein aus der Anmeldung; kein Werkzeug hat dafür einen Parameter.

3.1Aufruf über HTTP#

Werkzeuge werden mit der MCP-Methode tools/call aufgerufen. Claude und ChatGPT erledigen das selbst; das Beispiel zeigt, was dabei über die Leitung geht.

POST /mcp HTTP/1.1
Host: www.ledgerpilot.io
Authorization: Bearer <zugangsschluessel>
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "stapel_kennzahlen",
    "arguments": { "bericht_id": "…", "jahr": 2025 }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [{ "type": "text", "text": "{ … }" }],
    "structuredContent": { … },
    "isError": false
  }
}

Das Ergebnis steht zweimal in der Antwort: als lesbarer Text und als strukturiertes Objekt. Die Beispiele unten zeigen nur das strukturierte Objekt, gekürzt; die Werte sind Beispielwerte. Kann ein Werkzeug nicht antworten, kommt isError: true mit einem Satz, den der Assistent dir weitergibt (Abschnitt 5).

Gemeinsame Felder: name ist der Name, den du dem Bericht gegeben hast. Ist das ein technischer Dateiname, heißt der Bericht stattdessen nach Quelle und Jahr (z. B. „Interactive Brokers 2025“), und der Dateiname steht in dateiname. zeitraum ist der Teil des Steuerjahrs, für den der Bericht Daten hat, im Format JJJJMMTT. Gerechnet wird wie in der App über das Steuerjahr.

3.2berichte_auflisten#

Listet deine Berichte mit Name, Quelle, Steuerjahr, Zeitraum und ob sie freigeschaltet sind. importzeitraum nennt zusätzlich, was der Import insgesamt umfasst – auch über das Steuerjahr hinaus. Beispielberichte tragen beispiel: true. Berichte zur Anlage KAP erscheinen nicht (Abschnitt 5). Ist das Steuerjahr eines Berichts nicht erkennbar, steht dort null.

Keine Parameter.

// Aufruf
{ "name": "berichte_auflisten", "arguments": {} }

// Ergebnis (gekürzt)
{
  "berichte": [
    {
      "bericht_id": "…",
      "name": "Interactive Brokers 2025",
      "quelle": "ib",
      "steuerjahr": 2025,
      "beispiel": false,
      "dateiname": "…",
      "zeitraum": { "von": "20250101", "bis": "20251231" },
      "importzeitraum": { "von": "20240101", "bis": "20251231" },
      "freigeschaltet": true,
      "link": "https://www.ledgerpilot.io/app/bericht?id=…"
    },
    …
  ]
}

3.3bericht_stand#

Stand eines Berichts für ein Steuerjahr: Zeitraum, ob für dieses Jahr gekauft, und – falls nicht – der Preis aus dem Angebot und der Kaufhinweis mit dem Weg zum Freischalten.

bericht_idstringPflicht

Die Kennung aus berichte_auflisten.

jahrintegeroptional

Steuerjahr zwischen 2000 und 2100. Ohne Angabe gilt das Steuerjahr des Berichts; ist keines bekannt, fragt das Werkzeug danach. Liegt das Jahr außerhalb der Daten des Berichts, nennt die Antwort den Zeitraum, den der Bericht umfasst.

// Aufruf
{ "name": "bericht_stand", "arguments": { "bericht_id": "…", "jahr": 2025 } }

// Ergebnis – noch nicht gekauft (gekürzt)
{
  "bericht_id": "…",
  "name": "PayPal 2025",
  "quelle": "paypal",
  "steuerjahr": 2025,
  "zeitraum": { "von": "20250101", "bis": "20250930" },
  "freigeschaltet": false,
  "preis": "…",
  "hinweis": "Dieser Bericht ist noch nicht freigeschaltet. Einzelne Buchungen und Dateien gibt es hier im Chat nach dem Kauf (…). …",
  "link": "…"
}

3.4stapel_kennzahlen#

Gesamtwerte des DATEV-Buchungsstapels: Anzahl Buchungen, Summe Soll, Summe Haben, Zeitraum und das Ergebnis der Gegenprobe. Es gibt bewusst keine Aufteilung nach Konto oder Monat. Summen stehen in der Basiswährung; lassen sie sich nicht eindeutig bilden (mehrere Währungen, unlesbarer Betrag), steht null statt einer falschen Zahl. Enthält der Bericht für das Jahr keine Buchungen, ist kennzahlen gleich null und ein Hinweis nennt den fehlenden Zeitraum – nie „0 Buchungen“.

bericht_idstringPflicht

Die Kennung aus berichte_auflisten.

jahrintegeroptional

Steuerjahr zwischen 2000 und 2100. Ohne Angabe gilt das Steuerjahr des Berichts; ist keines bekannt, fragt das Werkzeug danach. Liegt das Jahr außerhalb der Daten des Berichts, nennt die Antwort den Zeitraum, den der Bericht umfasst.

// Aufruf
{ "name": "stapel_kennzahlen", "arguments": { "bericht_id": "…" } }

// Ergebnis (gekürzt)
{
  "bericht_id": "…",
  "steuerjahr": 2025,
  "kennzahlen": {
    "anzahl_buchungen": 1284,
    "summe_soll": "48210.37",
    "summe_haben": "48210.37",
    "zeitraum": { "von": "20250101", "bis": "20251231" },
    "gegenprobe": { "ok": true, "differenz": "0.00", … }
  }
}

// Ohne Gegenprobe zusätzlich (gekürzt)
{
  "kennzahlen": { …, "gegenprobe": { "ok": null, "differenz": null, … } },
  "gegenprobe_hinweis": "Für diesen Zeitraum gibt es keinen Stripe-Kontostand zum Abgleich (…). Das ist kein Fehler; …"
}

Gibt es für Bericht und Zeitraum keine Gegenprobe, bleiben ok und differenz leer, und gegenprobe_hinweis nennt den Grund je Quelle (z. B. kein Kontostand zum Abgleich). Das ist kein Fehler: Die App zeigt in denselben Fällen ebenfalls keine Gegenprobe. Eine Bestätigung wird nie erfunden.

3.5stapel_zeilen#

Die einzelnen Buchungen eines gekauften Berichts, seitenweise mit 100 Buchungen je Seite. Ohne Kauf kommt statt der Zeilen der Kaufhinweis (Abschnitt 4).

Jede Zeile kommt in einer Kurzform, für jede Quelle gleich, mit den Schlüsseln datum, betrag, sh (Soll/Haben), wkz (WKZ Umsatz), kurs, basis_betrag, basis_wkz (WKZ Basis-Umsatz), konto, gegenkonto, bu, beleg1, beleg2 und text. Das Feld spalten ordnet jedem Schlüssel die Spalte des DATEV-Buchungsstapels zu. Leere Felder fehlen; Kurs und Basis stehen nur bei Fremdwährung da. Jedes weitere gefüllte Feld (etwa USt-IdNr., EU-Steuersatz oder Kostenstelle) steht unter seinem DATEV-Namen in der Zeile; Felder mit demselben Wert in allen Zeilen stehen einmal in fuer_alle_zeilen. Die Werte sind unverändert, nicht umgerechnet oder gerundet. Alle Spalten enthält die Datei aus datei_abrufen.

bericht_idstringPflicht

Die Kennung aus berichte_auflisten.

jahrintegeroptional

Steuerjahr zwischen 2000 und 2100. Ohne Angabe gilt das Steuerjahr des Berichts; ist keines bekannt, fragt das Werkzeug danach. Liegt das Jahr außerhalb der Daten des Berichts, nennt die Antwort den Zeitraum, den der Bericht umfasst.

seiteintegeroptional

Seite ab 1, Vorgabe 1. seiten im Ergebnis nennt die Gesamtzahl. Eine Seite außerhalb des Bereichs liefert „Seite N gibt es nicht …“ mit der Anzahl der Buchungen und Seiten.

// Aufruf
{ "name": "stapel_zeilen", "arguments": { "bericht_id": "…", "seite": 2 } }

// Ergebnis – gekaufter Bericht (gekürzt)
{
  "bericht_id": "…",
  "steuerjahr": 2025,
  "seite": 2,
  "seiten": 13,
  "anzahl_buchungen": 1284,
  "spalten": {
    "datum": "Belegdatum",
    "betrag": "Umsatz (ohne Soll/Haben-Kz)",
    "sh": "Soll/Haben-Kennzeichen",
    …
  },
  "fuer_alle_zeilen": { "Herkunft-Kz": "RE", "Festschreibung": "0" },
  "zeilen": [
    { "datum": "1503", "betrag": "19,90", "sh": "S", "wkz": "EUR",
      "konto": "…", "gegenkonto": "…", "text": "…" },
    { "datum": "1803", "betrag": "250,00", "sh": "H", "wkz": "USD",
      "kurs": "…", "basis_betrag": "…", "basis_wkz": "EUR",
      "konto": "…", "gegenkonto": "…", "beleg1": "…", "text": "…" },
    …
  ]
}

3.6datei_abrufen#

Ein Download-Link für eine Datei eines gekauften Berichts: den DATEV-Buchungsstapel als CSV oder XLSX oder das Steuerberater-Paket als ZIP. Die Datei ist dieselbe wie beim Herunterladen in der App, mit deinen Einstellungen (Kontenrahmen, Berater- und Mandantennummer). Die Antwort nennt die Datei (datei), den Link (download) und seine Gültigkeit (gueltig_minuten); Einzelheiten in Abschnitt 4.3.

bericht_idstringPflicht

Die Kennung aus berichte_auflisten.

art"csv" | "xlsx" | "paket"optional

Vorgabe csv. paket ist das Steuerberater-Paket (ZIP).

jahrintegeroptional

Steuerjahr zwischen 2000 und 2100. Ohne Angabe gilt das Steuerjahr des Berichts; ist keines bekannt, fragt das Werkzeug danach. Liegt das Jahr außerhalb der Daten des Berichts, nennt die Antwort den Zeitraum, den der Bericht umfasst.

// Aufruf
{ "name": "datei_abrufen", "arguments": { "bericht_id": "…", "art": "paket" } }

// Ergebnis – gekaufter Bericht (gekürzt)
{
  "bericht_id": "…",
  "steuerjahr": 2025,
  "datei": "Steuerberater-Paket (ZIP)",
  "download": "https://www.ledgerpilot.io/api/assistent/download/<einmal-token>",
  "gueltig_minuten": 15,
  "hinweis": "Der Link gilt 15 Minuten und funktioniert genau einmal. Danach einfach erneut nach der Datei fragen."
}

3.7frage_stellen#

Stellt der Ledgerpilot-Frageleiste eine Frage zum Buchungsstapel und gibt ihre Antwort zurück – genau wie in der App. Vor dem Kauf enthält die Antwort denselben gekürzten Auszug wie dort. Ob ein Bericht gekauft ist, prüft der Server selbst; der Assistent kann es nicht vorgeben.

Die Sätze der Antwort sind die der App. hinweis_chat sagt dem Assistenten, dass Verweise wie „oben“ oder „diese Seite“ den Bericht in Ledgerpilot meinen. Für Beispielberichte und für Quellen, die die Frageleiste noch nicht kennt (derzeit Shopify), kommt statt einer Antwort eine Meldung mit Grund und Ausweg: Gesamtwerte über stapel_kennzahlen, die Tabelle in Ledgerpilot.

bericht_idstringPflicht

Die Kennung aus berichte_auflisten.

fragestringPflicht

Die Frage in eigenen Worten, 2 bis 500 Zeichen.

jahrintegeroptional

Steuerjahr zwischen 2000 und 2100. Ohne Angabe gilt das Steuerjahr des Berichts; ist keines bekannt, fragt das Werkzeug danach. Liegt das Jahr außerhalb der Daten des Berichts, nennt die Antwort den Zeitraum, den der Bericht umfasst.

// Aufruf
{
  "name": "frage_stellen",
  "arguments": {
    "bericht_id": "…",
    "frage": "Was habe ich im März an Gebühren gezahlt?"
  }
}

// Ergebnis (gekürzt)
{
  "bericht_id": "…",
  "steuerjahr": 2025,
  "antwort": {
    "satz": "…",
    …
  },
  "hinweis_chat": "Die Antwort stammt aus der Frageleiste der App. Verweise auf „oben“, „unten“ … meinen den Bericht in Ledgerpilot: …"
}

3.8daten_aktualisieren#

Ruft die angebundene Quelle eines Berichts neu ab, genau wie der Knopf „Aktualisieren“ in der App: Stripe, PayPal, Adyen, Mollie und Shopify über ihre Schnittstelle, Interactive Brokers über die gespeicherte Flex-Query. Dabei entsteht ein neuer Bericht mit den Daten bis heute; der bisherige bleibt unverändert. Der Assistent ruft das Werkzeug nur auf, wenn du ausdrücklich darum bittest. Ein Abruf kann bis zu zwei Minuten dauern.

Die Antwort nennt den neuen Bericht (neuer_bericht), den bisherigen (alter_bericht), die Kennzahlen des jüngsten Steuerjahrs und mit freigeschaltet, ob der neue Bericht schon gekauft ist; sonst steht der Preis dabei, gekauft wird in der App. Berichte aus hochgeladenen Dateien (auch flatex) lassen sich nur in der App erneuern; dann kommt der Weg dorthin. Beispielberichte lassen sich nicht aktualisieren.

bericht_idstringPflicht

Die Kennung aus berichte_auflisten.

// Aufruf
{ "name": "daten_aktualisieren", "arguments": { "bericht_id": "…" } }

// Ergebnis (gekürzt)
{
  "neuer_bericht": { "bericht_id": "…", "name": "Stripe 2026", "steuerjahr": 2026, … },
  "alter_bericht": "…",
  "link": "https://www.ledgerpilot.io/app/bericht?id=…",
  "kennzahlen": { "anzahl_buchungen": 312, "summe_soll": "…", "summe_haben": "…", … },
  "freigeschaltet": false,
  "preis": "…",
  "hinweis": "Neuer Bericht angelegt; der bisherige bleibt unverändert. Buchungen und Dateien des neuen Berichts gibt es nach dem Freischalten in Ledgerpilot: …"
}

4Kaufregel#

Der Assistent sieht nie mehr als du in der App vor dem Kauf. Jeder Abruf läuft über dieselbe Kaufprüfung wie die App, auf dem Server und für jeden Aufruf neu.

4.1Vor dem Kauf#

• Berichte, Stand und Kaufhinweis
• Gesamtwerte: Anzahl Buchungen, Summe Soll und Haben, Zeitraum, Gegenprobe
• die Frageleiste, mit dem gekürzten Auszug wie in der App

Die Tabelle des Buchungsstapels kannst du dir vor dem Kauf in der App ansehen. Im Chat gibt es einzelne Buchungen und Dateien erst nach dem Kauf; hier ist der Assistent bewusst strenger als die App.

stapel_zeilen und datei_abrufen antworten vor dem Kauf mit dem Kaufhinweis:

{
  "freigeschaltet": false,
  "hinweis": "Dieser Bericht ist noch nicht freigeschaltet. Einzelne Buchungen und Dateien gibt es hier im Chat nach dem Kauf (…). Gesamtwerte und Gegenprobe gibt es schon jetzt (stapel_kennzahlen), Fragen beantwortet frage_stellen. Die Tabelle kannst du in Ledgerpilot vor dem Kauf ansehen; gekauft wird dort. Freischalten: …",
  "link": "…"
}

4.2Nach dem Kauf#

Für gekaufte Berichte liefert der Server zusätzlich die Buchungszeilen und die Dateien. Gekauft wird immer in der App, nie im Chat: Der Assistent kann keinen Kauf auslösen und bekommt nur den Hinweis mit dem Weg zum Bericht. Beispielberichte gelten nie als gekauft. Auch für einen Bericht aus daten_aktualisieren prüft der Server den Kauf neu, wie in der App.

4.3Dateien#

Claude und ChatGPT können CSV-, Excel- und ZIP-Dateien nicht im Chat anzeigen. Für eine Datei bekommt der Assistent deshalb einen Download-Link auf /api/assistent/download/…, den er dir weitergibt.

• Er gilt 15 Minuten und funktioniert genau einmal, nur für diese eine Datei. Danach einfach erneut nach der Datei fragen.
• Er braucht keine Anmeldung; der Link selbst ist der Nachweis. Trennst du die Verbindung, ist er wertlos.
• Die Datei entsteht erst beim Klick, mit erneuter Kaufprüfung.

5Grenzen und Fehler#

Fehler eines Werkzeugs kommen als klarer Satz an den Assistenten, nie als interne Fehlermeldung.

6Datenschutz und Sicherheit#

• Übertragung an den Assistenten. Was der Assistent abruft, wird an den Anbieter des Assistenten (Anthropic bzw. OpenAI) übertragen und dort verarbeitet. Du entscheidest mit der Zustimmung, ob das geschieht.
• Schlüssel nur für den MCP-Endpunkt. Der Zugangsschlüssel des Assistenten gilt ausschließlich an /mcp. Jede andere Ledgerpilot-Adresse lehnt ihn ab.
• Keine Kaufrechte. Die Rechte berichte:lesen und dateien:lesen erlauben nur Lesen. daten:aktualisieren ruft nur die Quelle ab, die du in Ledgerpilot angebunden hast, und legt einen neuen Bericht an; bestehende Berichte ändert es nicht. Kaufen, Löschen, Hochladen und Einstellungen bleiben in der App.
• Verlauf. In den Ledgerpilot-Einstellungen siehst du unter „Verbundene Assistenten“ jede Verbindung und den Verlauf der Abrufe von Buchungszeilen und Dateien und der Aktualisierungen. Einträge werden 12 Monate aufbewahrt.
• Nur deine Daten. Eine Verbindung sieht ausschließlich die Berichte des Kontos, das ihr zugestimmt hat.