Vraag je AI-assistent hoeveel je vorige maand hebt uitgegeven, welke accounts afgestemd moeten worden, of waar een transactie thuishoort. Beancount MCP geeft het toegang tot de query's, accounts en bronbestanden van je gehoste grootboek, zodat het vanuit je boeken kan werken en het bewijs achter zijn antwoord kan tonen.
Met schrijftoestemming kan de assistent ook transacties toevoegen en grootboekbestanden bijwerken. Je kunt het vragen om ondersteunde bewerkingen te bekijken, de voorgestelde boekingen te controleren en het grootboek te controleren na een wijziging.
MCP staat voor Model Context Protocol: een standaard voor het verbinden van AI-toepassingen met externe tools en gegevens. Deze verbinding werkt met grootboeken die op Beancount.io worden gehost. De antwoorden van je assistent weerspiegelen de transacties en prijzen die daar zijn vastgelegd; het verbinden van MCP maakt die gegevens niet automatisch actueel.
Verbind je AI-client
Gebruik een client die externe MCP over Streamable HTTP ondersteunt. De server-URL is:
https://beancount.io/api-gateway/mcpClaude Code
Voeg de server toe vanaf je terminal:
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpOpen Claude Code, voer /mcp uit, selecteer beancount en volg de authenticatiestroom. Meld je aan bij Beancount.io en bekijk de aangevraagde machtigingen. Ga terug naar /mcp om de verbinding te bevestigen. Zie Claude Code's MCP-instructies voor clientspecifieke details.
De toestemmingspagina laat je de toegang beperken tot één grootboek of expliciet kiezen voor Alle toegankelijke grootboeken. Een beperking tot één grootboek is een nuttig startpunt. Bij bredere toegang moet je de assistent vertellen welk grootboek het moet gebruiken, zoals alice/personal; grootboektools moeten bij elke aanroep hun doel identificeren.
Claude Desktop en Claude op het web
Open Aanpassen → Connectors, kies Eigen connector toevoegen, voer de server-URL in en verbind je Beancount.io-account. Schakel de connector in voor het gesprek waar je het wilt gebruiken. Organisatieaccounts hebben mogelijk eerst een eigenaar nodig om de connector toe te voegen. Volg Claude's handleiding voor externe connectors.
Cursor
Voeg de server toe aan je persoonlijke ~/.cursor/mcp.json:
{
"mcpServers": {
"beancount": {
"url": "https://beancount.io/api-gateway/mcp"
}
}
}Voltooi de OAuth-aanmelding wanneer Cursor erom vraagt, en controleer vervolgens of de tools van de server beschikbaar zijn. Cursor's MCP-documentatie behandelt configuratie en toolgoedkeuringsinstellingen.
Persoonlijke API-sleutels
Voor een client die bearer-referenties accepteert, kun je een persoonlijke API-sleutel aanmaken in Instellingen → Persoonlijke toegangstokens. Voor het aanmaken van een sleutel is een betaald Beancount.io-abonnement vereist. Selecteer ledger.read voor query's, beperk de sleutel optioneel tot één grootboek en kopieer deze wanneer deze wordt getoond. Configureer de autorisatieheader van je client als Authorization: Bearer JOUW_SLEUTEL met behulp van de privé-referentie-instellingen.
Houd de sleutel buiten gedeelde projectconfiguratie. OAuth-clients beheren referenties via hun aanmeldstroom; je hoeft voor dat pad geen persoonlijke sleutel aan te maken.
Begin met een uitgavenvraag
Probeer dit na het verbinden, en vervang de grootboeknaam door die van jou:
Gebruik
alice/personal. Identificeer de accounts en valuta's, en vat vervolgens de uitgaven van augustus 2026 per account samen. Toon het datumbereik en de BQL achter elk totaal, houd valuta's gescheiden en rapporteer eventuele validatiefouten in het grootboek. Verander niets.
De assistent kan je grootboeken ontdekken met listLedgers, je accountnamen leren via getLedgerContext en runBqlQueryStructured uitvoeren voor getypeerde queryresultaten. checkLedger retourneert validatiefouten, aantal boekingen en de laatste commit.
Een nuttig antwoord bevat het grootboek, de periode, valuta's, totalen en ondersteunende query's. Vraag bij een vraag over het nettovermogen ook om de waarderingsmethode en de data van de gebruikte prijzen. Ontbrekende transacties of verouderde prijzen kunnen het antwoord veranderen, zelfs als het grootboek de validatie doorstaat.
Voeg een transactie toe met een voorbeeld
Voor nieuwe boekingen accepteert appendLedgerText gewone Beancount-tekst en stuurt richtlijnen naar bestanden volgens de configuratie van je grootboek. De optie dry_run retourneert een diff en verwachte validatiefouten vóór het vastleggen.
Bijvoorbeeld:
Bereid een koffieaankoop van 4,50 USD voor, gedateerd 15 september 2026, betaald vanaf
Assets:Cashen gecategoriseerd onderExpenses:Food. Controleer of die accounts bestaan en zoek eerst naar een overeenkomstige transactie. GebruikappendLedgerTextmetdry_run: true, toon de voorgestelde boeking en het bestandsverschil, en wacht op mijn bevestiging.
Met die accounts die al geopend zijn, zou de voorgestelde boeking er als volgt uitzien:
2026-09-15 * "Cafe" "Koffie"
Expenses:Food 4.50 USD
Assets:Cash -4.50 USDGebruik accountnamen uit je eigen grootboek en voltooi vervolgens de controle:
- Controleer de datum, het bedrag, de accounts en het doelbestand in het voorbeeld.
- Bevestig de exacte wijziging die je wilt dat de assistent toepast.
- Vraag het om
checkLedgeruit te voeren en de resulterende commit en eventuele fouten te rapporteren.
appendLedgerText wijst standaard nieuwe validatiefouten af. Algemene bestandswijzigingen gebruiken editLedgerFiles, die bestanden kunnen maken, vervangen, bijwerken of verwijderen in één Git-commit. Het voorbeeld rapporteert ook een diff en verwachte fouten. Controleer het resultaat en voer checkLedger uit na het schrijven: een succesvolle commit kan nog steeds boekhoudfouten bevatten.
Gebruik een workflow voor terugkerende boekhouding
De server biedt ook herbruikbare MCP-prompts. Clients met promptondersteuning tonen deze in hun opdracht- of promptkiezer:
| Workflow | Waar het je mee helpt |
|---|---|
spending-report | Beantwoord een uitgavenvraag met ondersteunende BQL en zonder grootboekschrijfacties. |
reconcile-account | Vergelijk één account met een verstrekt overzicht, classificeer verschillen en stel ontbrekende boekingen voor. |
close-month | Bekijk actieve accounts, saldoverificaties, terugkerende transacties en onopgeloste vlaggen. |
categorize-imports | Bekijk klaargezette banktransacties en stel categorieën voor met behulp van bestaande accounts. |
Deze prompts begeleiden de assistent door een procedure. Ze voeren geen boekhoudtaak uit alleen omdat je ze selecteert, en ze verlenen geen extra machtigingen.
Afstemming vereist een overzicht en een eindsaldo. Een schoon validatieresultaat alleen kan niet vaststellen dat elke transactie is geregistreerd. Vraag de assistent om alles te identificeren wat het niet kon verifiëren en laat die vragen zichtbaar in het rapport.
Voor bankimporten moet je eerst de bank koppelen in Beancount.io. Het lezen van verbindingsdetails vereist administratieve toegang; het indienen van klaargezette transacties vereist schrijftoestemming en de juiste toegang tot die bankverbinding. Bekijk voorgestelde categorieën en duplicaten voordat je de indiening autoriseert.
Begrijp toegang en gegevensverwerking
De machtigingen van de verbinding bepalen wat de assistent kan doen:
| Machtiging | Toegang |
|---|---|
ledger.read | Query en lees grootboekgegevens. |
ledger.write | Lees gegevens en voer gewone grootboekwijzigingen uit. |
ledger.admin | Lees, schrijf en voer administratieve bewerkingen uit waar geautoriseerd. |
Je bestaande toegang tot elk grootboek blijft van toepassing. Het beperken van een referentie tot één grootboek voorkomt dat grootboekaanroepen een ander doelwit hebben; een onbeperkte referentie kan kiezen uit de grootboeken waartoe je toegang hebt. De OAuth-client kiest welke machtigingen het aanvraagt, dus lees het toestemmingsscherm voordat je goedkeurt.
De MCP-server toont geen menselijk goedkeuringsdialoogvenster. De instellingen van je client bepalen wanneer het vraagt voordat het een tool aanroept, en voorbeelden moeten expliciet worden aangevraagd. De meegeleverde schrijfworkflows instrueren de assistent om op bevestiging te wachten. Een referentie beperkt tot ledger.read biedt een afgedwongen grens wanneer je analyse zonder schrijfacties wilt.
Toolresultaten, inclusief opgevraagde transacties en bestanden die de assistent leest, komen in de context van je AI-client en kunnen worden verwerkt door de modelprovider. Beancount.io bewaart je grootboek, Git-geschiedenis en operationele gegevens. Een stateless MCP-verbinding is geen belofte dat er geen gegevens worden bewaard; het gegevensbeleid van je client en provider is ook van toepassing.
Ingetrokken persoonlijke API-sleutels worden afgewezen bij volgende verzoeken. OAuth-toegangstokens duren normaal gesproken één uur; het intrekken van een verversingstoken maakt een reeds uitgegeven toegangstoken niet onmiddellijk ongeldig. Grootboektoegang wordt opnieuw gecontroleerd wanneer beveiligde bewerkingen worden uitgevoerd.
Veelgestelde vragen
Opent dit het grootboek op mijn laptop?
Het gehoste eindpunt werkt op je Beancount.io-grootboek. Het opent geen lokaal .bean-bestand en je hebt geen Fava-browsertabblad open nodig.
Hoe verschilt dit van de AI-assistent in het dashboard?
Het dashboard biedt zijn eigen chatinterface. MCP maakt grootboekmogelijkheden beschikbaar vanuit een externe AI-client, met de gespreks-, model- en goedkeuringsinstellingen van die client.
Waarom kan ik een tool zien maar niet gebruiken?
De toolcatalogus omvat bewerkingen die je referentie mogelijk niet toestaat. Controleer de fout en de verleende machtigingen. Een onbeperkte referentie heeft ook een expliciet grootboekdoel nodig voor grootboektools.
Verbind je grootboek en begin met één vraag die je tegen je boeken kunt verifiëren. Bewaar de query bij het antwoord en voeg vervolgens schrijfmachtigingen toe wanneer je hulp wilt bij het onderhouden van het grootboek zelf.
