Fragen Sie Ihren KI-Assistenten, wie viel Sie letzten Monat ausgegeben haben, welche Konten abgestimmt werden müssen oder wohin eine Transaktion gehört. Beancount MCP gibt ihm Zugriff auf die Abfragen, Konten und Quelldateien Ihres gehosteten Hauptbuchs, sodass er auf Grundlage Ihrer Bücher arbeiten und die Belege für seine Antwort zeigen kann.
Mit Schreibberechtigung kann der Assistent auch Transaktionen hinzufügen und Hauptbuchdateien aktualisieren. Sie können ihn bitten, unterstützte Änderungen in der Vorschau anzuzeigen, die vorgeschlagenen Einträge zu prüfen und das Hauptbuch nach einer Änderung zu überprüfen.
MCP steht für Model Context Protocol: ein Standard zum Verbinden von KI-Anwendungen mit externen Tools und Daten. Diese Verbindung funktioniert mit Hauptbüchern, die auf Beancount.io gehostet werden. Die Antworten Ihres Assistenten spiegeln die dort erfassten Transaktionen und Preise wider; das Verbinden von MCP macht diese Aufzeichnungen nicht automatisch aktuell.
Verbinden Sie Ihren KI-Client
Verwenden Sie einen Client, der Remote-MCP über Streamable HTTP unterstützt. Die Server-URL lautet:
https://beancount.io/api-gateway/mcpClaude Code
Fügen Sie den Server von Ihrem Terminal hinzu:
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpÖffnen Sie Claude Code, führen Sie /mcp aus, wählen Sie beancount aus und folgen Sie dem Authentifizierungsablauf. Melden Sie sich bei Beancount.io an und prüfen Sie die angeforderten Berechtigungen. Kehren Sie zu /mcp zurück, um die Verbindung zu bestätigen. Siehe Claude Codes MCP-Anweisungen für clientspezifische Details.
Die Zustimmungsseite ermöglicht es Ihnen, den Zugriff auf ein Hauptbuch zu beschränken oder explizit Alle zugänglichen Hauptbücher auszuwählen. Eine Beschränkung auf ein einzelnes Hauptbuch ist ein sinnvoller Ausgangspunkt. Bei breiterem Zugriff sagen Sie dem Assistenten, welches Hauptbuch verwendet werden soll, z. B. alice/personal; Hauptbuch-Tools müssen ihr Ziel bei jedem Aufruf identifizieren.
Claude Desktop und Claude im Web
Öffnen Sie Anpassen → Verbindungen, wählen Sie Benutzerdefinierte Verbindung hinzufügen, geben Sie die Server-URL ein und verbinden Sie Ihr Beancount.io-Konto. Aktivieren Sie die Verbindung für die Konversation, in der Sie sie verwenden möchten. Bei Organisationskonten muss möglicherweise zuerst ein Inhaber die Verbindung hinzufügen. Folgen Sie Claudes Anleitung für Remote-Verbindungen.
Cursor
Fügen Sie den Server zu Ihrer persönlichen ~/.cursor/mcp.json hinzu:
{
"mcpServers": {
"beancount": {
"url": "https://beancount.io/api-gateway/mcp"
}
}
}Schließen Sie die OAuth-Anmeldung ab, wenn Cursor sie anfordert, und prüfen Sie dann, ob die Tools des Servers verfügbar sind. Cursors MCP-Dokumentation behandelt Konfiguration und Tool-Genehmigungseinstellungen.
Persönliche API-Schlüssel
Für einen Client, der Bearer-Anmeldedaten akzeptiert, können Sie in Einstellungen → Persönliche Zugriffstoken einen persönlichen API-Schlüssel erstellen. Die Erstellung eines Schlüssels erfordert einen kostenpflichtigen Beancount.io-Tarif. Wählen Sie ledger.read für Abfragen, schränken Sie den Schlüssel optional auf ein Hauptbuch ein und kopieren Sie ihn, wenn er angezeigt wird. Konfigurieren Sie den Autorisierungsheader Ihres Clients als Authorization: Bearer YOUR_KEY über seine privaten Anmeldedaten-Einstellungen.
Bewahren Sie den Schlüssel außerhalb der gemeinsamen Projektkonfiguration auf. OAuth-Clients verwalten Anmeldedaten über ihren Anmeldeablauf; Sie müssen für diesen Weg keinen persönlichen Schlüssel erstellen.
Beginnen Sie mit einer Ausgabenfrage
Versuchen Sie dies nach dem Verbinden und ersetzen Sie den Hauptbuchnamen durch Ihren:
Verwenden Sie
alice/personal. Identifizieren Sie dessen Konten und Währungen und fassen Sie dann die Ausgaben für August 2028 nach Konto zusammen. Zeigen Sie den Datumsbereich und die BQL hinter jeder Summe an, halten Sie Währungen getrennt und melden Sie alle Hauptbuch-Validierungsfehler. Ändern Sie nichts.
Der Assistent kann Ihre Hauptbücher mit listLedgers entdecken, Ihre Kontonamen durch getLedgerContext lernen und runBqlQueryStructured für typisierte Abfrageergebnisse ausführen. checkLedger gibt Validierungsfehler, Eintragsanzahlen und den letzten Commit zurück.
Eine nützliche Antwort enthält das Hauptbuch, den Zeitraum, Währungen, Summen und unterstützende Abfragen. Bei einer Frage zum Nettovermögen fragen Sie auch nach der Bewertungsmethode und den Daten der verwendeten Preise. Fehlende Transaktionen oder veraltete Preise können die Antwort ändern, selbst wenn das Hauptbuch die Validierung besteht.
Hinzufügen einer Transaktion mit Vorschau
Für neue Einträge akzeptiert appendLedgerText gewöhnlichen Beancount-Text und leitet Anweisungen an Dateien weiter, die Ihre Hauptbuchkonfiguration verwendet. Die Option dry_run gibt einen Diff und voraussichtliche Validierungsfehler zurück, bevor der Commit erfolgt.
Zum Beispiel:
Bereiten Sie einen Kaffeekauf über 4,50 USD vom 15. September 2026 vor, bezahlt von
Assets:Cashund kategorisiert unterExpenses:Food. Prüfen Sie, ob diese Konten existieren, und suchen Sie zuerst nach einer passenden Transaktion. Verwenden SieappendLedgerTextmitdry_run: true, zeigen Sie den vorgeschlagenen Eintrag und den Datei-Diff und warten Sie auf meine Bestätigung.
Wenn diese Konten bereits eröffnet sind, würde der vorgeschlagene Eintrag folgendermaßen aussehen:
2026-09-15 * "Cafe" "Kaffee"
Expenses:Food 4.50 USD
Assets:Cash -4.50 USDVerwenden Sie Kontonamen aus Ihrem eigenen Hauptbuch und schließen Sie die Prüfung ab:
- Überprüfen Sie Datum, Betrag, Konten und Zieldatei in der Vorschau.
- Bestätigen Sie die genaue Änderung, die der Assistent anwenden soll.
- Bitten Sie ihn,
checkLedgerauszuführen und den resultierenden Commit und alle Fehler zu melden.
appendLedgerText lehnt neue Validierungsfehler standardmäßig ab. Allgemeine Dateiänderungen verwenden editLedgerFiles, das Dateien in einem einzigen Git-Commit erstellen, ersetzen, aktualisieren oder löschen kann. Seine Vorschau meldet ebenfalls einen Diff und voraussichtliche Fehler. Überprüfen Sie das Ergebnis und führen Sie nach dem Schreiben checkLedger aus: Ein erfolgreicher Commit kann dennoch Buchhaltungsfehler enthalten.
Verwenden Sie einen Workflow für wiederkehrende Buchhaltung
Der Server stellt auch wiederverwendbare MCP-Prompts bereit. Clients mit Prompt-Unterstützung zeigen diese in ihrem Befehls- oder Prompt-Auswähler an:
| Workflow | Wobei er hilft |
|---|---|
spending-report | Beantwortung einer Ausgabenfrage mit unterstützender BQL und ohne Hauptbuch-Schreibvorgänge. |
reconcile-account | Vergleich eines Kontos mit einem gelieferten Kontoauszug, Klassifizierung von Differenzen und Vorschlag fehlender Einträge. |
close-month | Überprüfung aktiver Konten, Saldenbestätigungen, wiederkehrender Transaktionen und ungeklärter Kennzeichnungen. |
categorize-imports | Überprüfung gestaffelter Banktransaktionen und Vorschlag von Kategorien anhand bestehender Konten. |
Diese Prompts führen den Assistenten durch ein Verfahren. Sie führen keinen Buchhaltungsjob nur durch ihre Auswahl aus und gewähren keine zusätzlichen Berechtigungen.
Für den Abgleich sind ein Kontoauszug und ein Endsaldo erforderlich. Ein sauberes Validierungsergebnis allein kann nicht belegen, dass jede Transaktion erfasst wurde. Bitten Sie den Assistenten, alles zu identifizieren, was er nicht verifizieren konnte, und lassen Sie diese Fragen im Bericht sichtbar.
Für Bankimporte verbinden Sie zuerst die Bank in Beancount.io. Das Lesen von Verbindungsdetails erfordert administrativen Zugriff: das Übermitteln gestaffelter Transaktionen erfordert Schreibberechtigung und den entsprechenden Zugriff auf diese Bankverbindung. Überprüfen Sie vorgeschlagene Kategorien und Duplikate, bevor Sie die Übermittlung autorisieren.
Zugriff und Datenverarbeitung verstehen
Die Berechtigungen der Verbindung bestimmen, was der Assistent tun kann:
| Berechtigung | Zugriff |
|---|---|
ledger.read | Hauptbuchdaten abfragen und lesen. |
ledger.write | Daten lesen und gewöhnliche Hauptbuchänderungen vornehmen. |
ledger.admin | Lesen, schreiben Sie Daten und führen Sie administrative Operationen aus, wo autorisiert. Daten berechtigen und administrative Operationen ausführen, wo autorisiert. |
Ihr bestehender Zugriff auf die einzelnen Hauptbücher gilt weiterhin. Die Beschränkung einer Anmeldedaten-Berechtigung auf ein Hauptbuch verhindert, dass Hauptbuchaufrufe auf ein anderes Ziel; eine unbeschränkte Anmeldedaten können zwischen den Hauptbüchern wählen, auf die Sie zugreifen können. Der OAuth-Client wählt aus, welche Berechtigungen er anfordert. Lesen Sie die Zustimmungsseite, bevor Sie zustimmen.
Der MCP-Server zeigt keinen menschlichen Genehmigungsdialog. Die Einstellungen Ihres Clients bestimmen, wann er vor dem Aufruf eines Tools fragt, und Vorschauen müssen explizit angefordert werden. Die gelieferten Schreibarbeitsabläufe weisen den Assistenten an, auf eine Bestätigung zu warten. Eine Anmeldedaten-Berechtigung auf ledger.read bietet eine durchgesetzte Grenze, wenn Sie Analyse ohne Schreibvorgänge wünschen verwenden möchten.
Tool-Ergebnisse, einschließlich abgefragter Transaktionen und Dateien, die der Assistent liest, gelangen in den Kontext Ihres KI-Clients und können von dessen Modellanbieter verarbeitet werden. Beancount.io behält Ihr Hauptbuch, die Git-Historie und Betriebsaufzeichnungen. Eine zustandslose MCP-Verbindung ist kein Versprechen, dass keine Daten gespeichert werden; die Datenrichtlinien Ihres Clients und Anbieters gelten ebenfalls.
Widerrufene persönliche API-Schlüssel werden bei nachfolgenden Anfragen abgelehnt. OAuth-Zugriffstoken halten normalerweise eine Stunde; der Widerruf eines Aktualisierungstokens macht ein bereits ausgestelltes Zugriffstoken nicht sofort ungültig. Der Hauptbuchzugriff wird erneut geprüft, wenn geschützte Operationen ausgeführt werden.
Häufige Fragen
Öffnet dies das Hauptbuch auf meinem Laptop?
Der gehostete Endpunkt arbeitet auf Ihrem Beancount.io-Hauptbuch. Er öffnet keine lokale .bean-Datei, und Sie benötigen kein geöffnetes Fava-Browser-Tab.
Wie unterscheidet sich dies vom KI-Assistenten im Dashboard?
Das Dashboard bietet eine eigene Chat-Oberfläche. MCP macht Hauptbuchfunktionen über einen externen KI-Client verfügbar, mit dessen Konversations-, Modell- und Genehmigungseinstellungen.
Warum kann ich ein Tool sehen, aber nicht verwenden?
Der Tool-Katalog enthält Operationen, die Ihre Anmeldedaten-Berechtigung möglicherweise nicht erlauben. Überprüfen Sie den Fehler und die gewährten Berechtigungen. Eine unbeschränkte Anmeldedaten-Berechtigung benötigt auch ein explizites Hauptbuchziel für Hauptbuch-Tools.
Verbinden Sie Ihr Hauptbuch und beginnen Sie mit einer Frage, die Sie gegen Ihre Bücher verifizieren können. Behalten Sie die Abfrage mit der Antwort und fügen Sie Schreibberechtigungen hinzu, wenn Sie Hilfe bei der Pflege des Hauptbuchs selbst wünschen.
