Beancount MCP: Verbinden Sie Ihr Ledger mit Claude, Cursor und jedem KI-Assistenten

Web Beancount startet MCP-Server – Sprechen Sie mit Ihrem Ledger von Claude, Cursor und jedem KI-Tool aus, das Sie bereits nutzen

Ihre Buchhaltungsdaten treffen auf Ihren KI-Workflow. Kein Kopieren und Einfügen. Keine Exporte. Einfach fragen.

Heute kündigt Web Beancount den Beancount-MCP-Server an – einen Model-Context-Protocol-(MCP-)Endpunkt, mit dem Sie Ihr Beancount-Ledger direkt mit Claude Desktop, Claude Code, Cursor, Windsurf oder jedem anderen MCP-kompatiblen KI-Client verbinden können. Zum ersten Mal können Power-User Buchhaltungsfragen stellen, BQL-Abfragen ausführen und sogar Ledger-Dateien bearbeiten – direkt aus den KI-Tools heraus, in denen sie ohnehin schon leben – ohne Tabs zu wechseln oder ihren Workflow zu verlassen.

Plain-Text-Beancount-Dateien sind gerade deshalb mächtig, weil sie einfach nur Dateien sind. Aber die Beantwortung der Frage „Wie viel habe ich letztes Quartal für Reisen ausgegeben?" erfordert immer noch, die BQL-Syntax zu kennen, zu wissen, wo Ihre Dateien liegen, und die Ergebnisse in einen Chat zu kopieren. Der Beancount-MCP-Server beseitigt diese Reibung vollständig.

Mit dem in Ihrem KI-Client konfigurierten Beancount-MCP-Server können Sie:

„Wie hoch ist mein Nettovermögen heute?" fragen und eine Live-Antwort erhalten, die aus Ihrem tatsächlichen Ledger stammt
Eine Zusammenfassung der Ausgaben des letzten Monats anfordern und die KI die BQL-Abfrage für Sie schreiben lassen
Der KI sagen, sie soll eine Transaktion hinzufügen, und zusehen, wie sie die Änderung in das git-Repository Ihres Ledgers committet
Ihre .beancount-Dateien durchsuchen und lesen, ohne jemals Ihren Editor zu verlassen

Der Server ist Ledger-gebunden: Jede MCP-Sitzung ist mit OAuth 2.1 für genau ein Ledger autorisiert. Clients wie Claude Code entdecken den Autorisierungsablauf und schließen ihn automatisch ab – keine manuelle Token-Verwaltung erforderlich. Ihr Ledger bleibt dort, wo es bereits liegt, im Web-Beancount-Backend: Der KI-Client sendet strukturierte Tool-Aufrufe an unseren Server, der Ihr Ledger in Ihrem Auftrag liest oder bearbeitet und die Ergebnisse zurückgibt. Der MCP-Server selbst speichert nichts über das hinaus, was die Konversation Ihres KI-Clients selbst enthält.

Der Beancount-MCP-Server ist ab heute für alle Web-Beancount-Nutzer verfügbar.

Erste Schritte

Der Beancount-MCP-Server ist live. Fügen Sie ihn in unter einer Minute zu Ihrem KI-Client hinzu.

MCP-Server-URL

https://beancount.io/api-gateway/mcp

Claude Code (empfohlen – vollständiger OAuth-2.1-Ablauf, kein Token nötig)

claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp

Bei der ersten Verwendung öffnet Claude Code ein Browserfenster. In der Browser-Eingabeaufforderung wählen Sie aus, welches Ledger verbunden werden soll – einmal genehmigen, und die Anmeldedaten werden automatisch aktualisiert. Haben Sie mehr als ein Ledger? Fügen Sie den Server erneut unter einem anderen Namen hinzu (claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp) und autorisieren Sie das andere Ledger in seiner eigenen Eingabeaufforderung.

Claude Desktop / Cursor / Windsurf / Zed

Fügen Sie den Server zur MCP-Konfiguration Ihres Clients hinzu (claude_desktop_config.json oder gleichwertig). Clients mit OAuth-2.1-Unterstützung öffnen bei der ersten Verwendung dieselbe Browser-Eingabeaufforderung – wählen Sie dort Ihr Ledger aus:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp"
    }
  }
}

Wenn Ihr Client den OAuth-Ablauf noch nicht unterstützt, generieren Sie ein statisches Token (auf ein Ledger beschränkt) in Ihren beancount.io-Kontoeinstellungen und übergeben Sie es als Header:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Sie haben noch kein Web-Beancount-Konto? Registrieren Sie sich unter beancount.io – Ihr Ledger ist nur einen git push entfernt.

Häufig gestellte Fragen

FAQs für Kunden

Was ist MCP und warum ist es für Beancount wichtig?

MCP (Model Context Protocol) ist ein offener Standard, der es KI-Assistenten ermöglicht, externe Tools und Datenquellen auf strukturierte, sichere Weise aufzurufen. Stellen Sie es sich wie einen USB-Anschluss für KI vor: Anstatt zu raten oder Sie zu bitten, Daten einzufügen, verbindet sich die KI direkt mit Ihren Systemen. Für Beancount-Nutzer bedeutet dies, dass Ihr KI-Client Ihre echten Ledger-Daten abfragen, Ihre tatsächlichen Dateien lesen und präzise Änderungen vornehmen kann – nicht raten, was sie enthalten könnten.

Welche KI-Clients funktionieren mit dem Beancount-MCP-Server?

Jeder MCP-kompatible Client, der OAuth 2.1 unterstützt, funktioniert sofort. Der Beancount-MCP-Server implementiert den vollständigen OAuth-2.1-Autorisierungsablauf mit PKCE, sodass Clients wie Claude Code automatisch den Autorisierungs-Endpunkt des Servers entdecken und Sie zur Anmeldung auffordern – kein manuelles Kopieren von Token oder Konfigurieren erforderlich. Sobald Sie den Zugriff genehmigen, speichert und aktualisiert der Client die Anmeldedaten automatisch.

Zu den Clients mit bekannter MCP-+-OAuth-2.1-Unterstützung gehören Claude Code CLI, Claude Desktop, Cursor, Windsurf und Zed. Mit dem Wachstum des MCP-Ökosystems funktioniert jeder neue Client, der der OAuth-2.1-MCP-Spezifikation folgt, ohne Änderungen auf unserer Seite.

Wie verbinde ich mein Ledger?

Für Clients, die OAuth 2.1 unterstützen (wie Claude Code):

Fügen Sie die URL des Beancount-MCP-Servers zur MCP-Konfiguration Ihres Clients hinzu.
Der Client öffnet automatisch ein Browserfenster, um den Zugriff zu autorisieren.
Melden Sie sich mit Ihrem Web-Beancount-Konto an und wählen Sie das Ledger aus, dem Sie Zugriff gewähren möchten.
Fertig – der Client übernimmt ab hier die Speicherung und Aktualisierung des Tokens.

Für Clients ohne OAuth-2.1-Unterstützung generieren Sie ein statisches Token (auf ein Ledger beschränkt) in Ihren Web-Beancount-Kontoeinstellungen und übergeben es als Authorization: Bearer-Header.

Ist das dasselbe wie die „Ask AI"-Chatfunktion im Dashboard?

Sie nutzen dieselben zugrunde liegenden Ledger-Tools (BQL-Abfragen, Datei-Lese-/Schreibzugriff), aber der MCP-Server ist ein anderer Einstiegspunkt. Die Ask-AI-Funktion des Dashboards ist ein gehostetes Chat-Erlebnis mit einer Cloudflare-gestützten Claude-Code-Sandbox. Der MCP-Server ist ein Protokoll-Endpunkt, mit dem Sie sich von Ihrem eigenen KI-Client Ihrer Wahl verbinden – was Ihnen mehr Kontrolle, mehr Modelle und eine tiefere Integration in Ihren bestehenden Workflow bietet.

Was kann die KI tatsächlich mit meinem Ledger tun?

Der MCP-Server stellt vier Tools bereit:

Tool	Funktion
`runBqlQuery`	BQL (Beancount Query Language) ausführen, um Salden, Transaktionen und Konten abzufragen
`listLedgerFiles`	Die Verzeichnisstruktur Ihres Ledger-Repositorys durchsuchen
`readLedgerFiles`	Den Inhalt von `.beancount`-Dateien und anderen Ledger-Dokumenten lesen
`editLedgerFiles`	Dateien in einem atomaren git-Commit erstellen, aktualisieren, ersetzen oder löschen

Die KI kann diese kombinieren: Ihre Dateistruktur entdecken, relevante Dateien für den Kontext lesen, eine BQL-Abfrage schreiben, um Ihre Frage zu beantworten, oder eine Änderung vorschlagen und committen.

Kann die KI mein Ledger ändern, ohne dass ich davon weiß?

Dateiänderungen erfordern, dass der KI-Client editLedgerFiles mit einer Beschreibung dessen aufruft, was er ändert. Gut funktionierende MCP-Clients (einschließlich Claude Code) zeigen Ihnen dies vor der Ausführung an. Änderungen unterstützen außerdem einen dry_run-Modus, der die genauen Änderungen als Vorschau anzeigt, ohne etwas zu schreiben, sodass Ihr Client Ihnen zuerst ein Diff zeigen kann. Und jede committete Änderung ist ein echter git-Commit im Repository Ihres Ledgers, sodass Sie einen vollständigen Prüfpfad haben und alles mit gängigen git-Tools rückgängig machen können.

Werden meine Daten an Dritte gesendet?

Ihre Ledger-Daten fließen durch das Web-Beancount-Backend (das Ihr Ledger bereits verwaltet) und werden als strukturierte Ergebnisse an Ihren KI-Client zurückgegeben. Das von Ihnen verwendete KI-Modell (zum Beispiel Claude) erhält die Tool-Ergebnisse wie jeden anderen Kontext. Der MCP-Server speichert keine Daten über das hinaus, was die Konversation Ihres KI-Clients bereits enthält.

Jedes Token ist Ledger-gebunden – was bedeutet das?

Wenn Sie den MCP-Server autorisieren, wählen Sie aus, welchem Ledger Sie Zugriff gewähren. Diese Sitzung kann nur auf dieses Ledger zugreifen. Wenn Sie mehrere Ledger haben, autorisieren Sie separate Sitzungen. Das begrenzt den Schadensradius: Eine Sitzung für Ihr persönliches Ledger kann Ihr geschäftliches Ledger nicht berühren.

Erfordert der MCP-Server, dass die Fava-Weboberfläche läuft?

Nein. Der MCP-Server kommuniziert mit der internen Fava-API, die von der Infrastruktur von Web Beancount verwaltet wird (Fava ist die Weboberfläche, die Ihr beancount.io-Ledger antreibt). Sie müssen die Fava-Oberfläche nicht geöffnet oder zugänglich haben.

Was passiert, wenn ich meinen MCP-Zugriff widerrufe?

Laufende MCP-Sitzungen erhalten beim nächsten Tool-Aufruf 401-Fehler. Clients, die OAuth 2.1 unterstützen, versuchen automatisch, sich neu zu autorisieren, und fordern Sie auf, sich erneut anzumelden.

Unter der Haube

Für die technisch Neugierigen – wie der Server aufgebaut ist.

Warum MCP statt einer eigenen API/eines eigenen Plugins pro KI-Tool?

MCP ist der aufkommende Standard und wird bereits von allen großen KI-Editoren unterstützt. Der Bau eines einzigen konformen MCP-Servers verschafft uns auf einen Schlag Kompatibilität mit dem gesamten Ökosystem, anstatt separate Integrationen für Claude, Cursor, Windsurf und was auch immer nächstes Quartal erscheint zu pflegen. Das Protokoll übernimmt Discovery, Tool-Schemas und Streaming – wir konzentrieren uns auf die Domänenlogik.

Warum OAuth 2.1 statt statischer API-Schlüssel?

OAuth 2.1 mit PKCE ist das, was die MCP-Spezifikation für Remote-Server empfiehlt, und das, was Clients wie Claude Code nativ implementieren. Der praktische Vorteil: Nutzer kommen nie mit einem Token in Berührung. Der Client entdeckt den Autorisierungsserver über unseren .well-known/oauth-protected-resource-Metadaten-Endpunkt, schließt PKCE ab und verwaltet die Aktualisierung automatisch. Statische Token werden weiterhin als Fallback für Clients unterstützt, die den vollständigen Ablauf nicht implementiert haben.

Warum Streamable HTTP statt SSE- oder stdio-Transport?

Streamable HTTP ist der MCP-Transport, der für Remote-Server über HTTPS konzipiert ist. Stdio ist für lokale Prozesse. SSE (der ältere MCP-Transport) wird zugunsten von Streamable HTTP abgekündigt. Unsere Nutzer verbinden sich von KI-Clients aus, die nicht am selben Ort wie unser Server liegen, daher ist Streamable HTTP die richtige und zukunftsorientierte Wahl.

Warum ist die MCP-Sitzung zustandslos (kein sessionIdGenerator)?

Wir setzen sessionIdGenerator: undefined, um jede Anfrage vollständig zustandslos zu machen – zwischen den Tool-Aufrufen wird kein serverseitiger Sitzungszustand zugewiesen oder gehalten. Dies entspricht dem zustandslosen Modus der Streamable-HTTP-Spezifikation und hält den Server horizontal skalierbar ohne Sitzungsaffinität. Der Tool-Kontext (Ledger-Identität, Fava-API-Client) wird pro Anfrage aus dem validierten OIDC-Token rekonstruiert.

Wie funktioniert die Überprüfung des Ledger-Zugriffs?

Nach der Validierung des OIDC-Tokens prüft resolveLedgerAccess über die Fava-API, dass der authentifizierte Nutzer tatsächlich Zugriff auf das angeforderte Ledger hat. Dies verhindert, dass ein gültiges Token für ein Ledger verwendet wird, um das Ledger eines anderen Nutzers auszuspähen (Defense-in-Depth zusätzlich zum signierten Token).

Wohin committet editLedgerFiles?

Es ruft changeLedgerFiles auf der Fava-API auf, die einen git-Commit im Gitea-Repository des Ledgers mit der Nachricht AI edit: <description> erstellt. Die Beschreibung stammt aus dem description-Feld, das die KI ausfüllt – und wird dem Nutzer in gut funktionierenden MCP-Clients vor der Ausführung angezeigt.

Was ist die dry_run-Option von editLedgerFiles?

dry_run: true validiert alle Dateioperationen (prüft, ob Dateien existieren, verifiziert, dass die alten Zeichenketten von str_replace genau einmal übereinstimmen) und gibt eine Vorschau dessen zurück, was committet würde – ohne tatsächlich in git zu schreiben. Dies ist nützlich für KI-Clients, die dem Nutzer vor dem Committen ein Diff zeigen möchten.

Welche Fehler sind für KI-Clients sichtbar?

Tool-Fehler werden als { isError: true, content: [{ type: "text", text: "..." }] } zurückgegeben – das strukturierte Fehlerformat des MCP-SDK. Der KI-Client erhält die Fehlermeldung als Text und kann entscheiden, wie er damit umgeht (erneut versuchen, dem Nutzer melden usw.). Auth-Fehler auf HTTP-Ebene (401) enthalten einen WWW-Authenticate-Header, der auf die OAuth-Protected-Resource-Metadaten verweist, sodass konforme Clients den Autorisierungsablauf automatisch erneut einleiten können.