Beancount MCP: Verbind je grootboek met Claude, Cursor en elke AI-assistent

Web Beancount lanceert MCP-server — Praat met je grootboek vanuit Claude, Cursor en elke AI-tool die je al gebruikt

Je boekhoudgegevens ontmoeten je AI-workflow. Geen kopiëren-plakken. Geen exports. Vraag het gewoon.

Vandaag kondigt Web Beancount de Beancount MCP-server aan — een Model Context Protocol (MCP)-endpoint waarmee je je Beancount-grootboek rechtstreeks kunt verbinden met Claude Desktop, Claude Code, Cursor, Windsurf of elke andere MCP-compatibele AI-client. Voor het eerst kunnen power-users boekhoudvragen stellen, BQL-query's uitvoeren en zelfs grootboekbestanden bewerken vanuit de AI-tools waarin ze al leven — zonder tabbladen te wisselen of hun workflow te verlaten.

Plain-text Beancount-bestanden zijn juist krachtig omdat het gewoon bestanden zijn. Maar het beantwoorden van "hoeveel heb ik vorig kwartaal aan reizen uitgegeven?" vereist nog steeds kennis van de BQL-syntaxis, weten waar je bestanden staan en het kopiëren van resultaten naar een chat. De Beancount MCP-server verwijdert die frictie volledig.

Met de Beancount MCP-server geconfigureerd in je AI-client kun je:

"Wat is mijn nettovermogen vandaag?" vragen en een live antwoord krijgen dat uit je werkelijke grootboek is gehaald
Om een samenvatting van de uitgaven van vorige maand vragen en de AI de BQL-query voor je laten schrijven
De AI vertellen om een transactie toe te voegen en toekijken hoe hij de wijziging vastlegt in de git-repository van je grootboek
Je .beancount-bestanden bekijken en lezen zonder ooit je editor te verlaten

De server is grootboek-gebonden: elke MCP-sessie is geautoriseerd voor precies één grootboek via OAuth 2.1. Clients zoals Claude Code ontdekken en voltooien de autorisatieflow automatisch — geen handmatig tokenbeheer nodig. Je grootboek blijft waar het al staat, op de Web Beancount-backend: de AI-client stuurt gestructureerde tool-aanroepen naar onze server, die je grootboek namens jou leest of bewerkt en de resultaten teruggeeft. De MCP-server zelf slaat niets op buiten wat het gesprek van je AI-client zelf bevat.

De Beancount MCP-server is vanaf vandaag beschikbaar voor alle Web Beancount-gebruikers.

Aan de slag

De Beancount MCP-server is live. Voeg hem in minder dan een minuut toe aan je AI-client.

MCP-server-URL

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

Claude Code (aanbevolen — volledige OAuth 2.1-flow, geen token nodig)

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

Bij het eerste gebruik opent Claude Code een browservenster. Bij de browserprompt kies je welk grootboek je wilt verbinden — keur één keer goed, en de inloggegevens worden automatisch vernieuwd. Heb je meer dan één grootboek? Voeg de server nogmaals toe onder een andere naam (claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp) en autoriseer het andere grootboek in zijn eigen prompt.

Claude Desktop / Cursor / Windsurf / Zed

Voeg de server toe aan de MCP-configuratie van je client (claude_desktop_config.json of gelijkwaardig). Clients met OAuth 2.1-ondersteuning openen bij het eerste gebruik dezelfde browserprompt — kies daar je grootboek:

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

Als je client de OAuth-flow nog niet ondersteunt, genereer dan een statisch token (gebonden aan één grootboek) via de accountinstellingen van je beancount.io en geef het door als header:

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

Heb je geen Web Beancount-account? Meld je aan op beancount.io — je grootboek is één git push verwijderd.

Veelgestelde vragen

Klantvragen

Wat is MCP en waarom is het belangrijk voor Beancount?

MCP (Model Context Protocol) is een open standaard waarmee AI-assistenten externe tools en gegevensbronnen op een gestructureerde, veilige manier kunnen aanroepen. Zie het als een USB-poort voor AI: in plaats van dat de AI raadt of je vraagt om gegevens te plakken, maakt het rechtstreeks verbinding met je systemen. Voor Beancount-gebruikers betekent dit dat je AI-client je echte grootboekgegevens kan opvragen, je werkelijke bestanden kan lezen en precieze bewerkingen kan maken — niet raden wat ze zouden kunnen bevatten.

Welke AI-clients werken met de Beancount MCP-server?

Elke MCP-compatibele client die OAuth 2.1 ondersteunt, werkt direct out of the box. De Beancount MCP-server implementeert de volledige OAuth 2.1-autorisatieflow met PKCE, zodat clients zoals Claude Code automatisch het autorisatie-endpoint van de server ontdekken en je vragen in te loggen — geen handmatig token kopiëren of configureren vereist. Zodra je de toegang goedkeurt, slaat de client de inloggegevens op en vernieuwt ze automatisch.

Clients met bekende MCP + OAuth 2.1-ondersteuning zijn onder meer Claude Code CLI, Claude Desktop, Cursor, Windsurf en Zed. Naarmate het MCP-ecosysteem groeit, zal elke nieuwe client die de OAuth 2.1 MCP-specificatie volgt, werken zonder wijzigingen aan onze kant.

Hoe verbind ik mijn grootboek?

Voor clients die OAuth 2.1 ondersteunen (zoals Claude Code):

Voeg de URL van de Beancount MCP-server toe aan de MCP-configuratie van je client.
De client opent automatisch een browservenster om toegang te autoriseren.
Log in met je Web Beancount-account en kies het grootboek waartoe je toegang wilt verlenen.
Klaar — de client regelt vanaf hier de tokenopslag en -vernieuwing.

Voor clients zonder OAuth 2.1-ondersteuning genereer je een statisch token (gebonden aan één grootboek) via de accountinstellingen van je Web Beancount en geef je het door als een Authorization: Bearer-header.

Is dit hetzelfde als de "Ask AI"-chatfunctie in het dashboard?

Ze delen dezelfde onderliggende grootboektools (BQL-query's, bestanden lezen/schrijven), maar de MCP-server is een ander toegangspunt. De Ask AI-functie van het dashboard is een gehoste chatervaring met een door Cloudflare aangedreven Claude Code-sandbox. De MCP-server is een protocol-endpoint waarmee je verbinding maakt vanuit je eigen AI-client naar keuze — wat je meer controle, meer modellen en diepere integratie met je bestaande workflow geeft.

Wat kan de AI eigenlijk doen met mijn grootboek?

De MCP-server stelt vier tools beschikbaar:

Tool	Wat het doet
`runBqlQuery`	Voer BQL (Beancount Query Language) uit om saldi, transacties en rekeningen op te vragen
`listLedgerFiles`	Blader door de mappenstructuur van je grootboekrepository
`readLedgerFiles`	Lees de inhoud van `.beancount`-bestanden en andere grootboekdocumenten
`editLedgerFiles`	Bestanden aanmaken, bijwerken, vervangen of verwijderen in één atomaire git-commit

De AI kan deze combineren: je bestandsstructuur ontdekken, relevante bestanden lezen voor context, een BQL-query schrijven om je vraag te beantwoorden, of een bewerking voorstellen en vastleggen.

Kan de AI mijn grootboek wijzigen zonder dat ik het weet?

Bestandsbewerkingen vereisen dat de AI-client editLedgerFiles aanroept met een beschrijving van wat het wijzigt. Goed-gedragende MCP-clients (waaronder Claude Code) tonen dit aan je voordat ze het uitvoeren. Bewerkingen ondersteunen ook een dry_run-modus die de exacte wijzigingen voorvertoont zonder iets te schrijven, zodat je client je eerst een diff kan tonen. En elke vastgelegde wijziging is een echte git-commit in de repository van je grootboek, dus je hebt een volledig auditspoor en kunt alles terugdraaien met standaard git-tools.

Worden mijn gegevens naar een derde partij gestuurd?

Je grootboekgegevens stromen door de Web Beancount-backend (die je grootboek al beheert) en worden als gestructureerde resultaten teruggegeven aan je AI-client. Het AI-model dat je gebruikt (bijvoorbeeld Claude) ontvangt de tool-resultaten zoals elke andere context. Er worden geen gegevens opgeslagen door de MCP-server buiten wat het gesprek van je AI-client al bevat.

Elk token is grootboek-gebonden — wat betekent dat?

Wanneer je de MCP-server autoriseert, kies je aan welk grootboek je toegang verleent. Die sessie heeft alleen toegang tot dat grootboek. Als je meerdere grootboeken hebt, autoriseer je aparte sessies. Dit beperkt de impactstraal: een sessie voor je persoonlijke grootboek kan je zakelijke grootboek niet raken.

Vereist de MCP-server dat de Fava-webinterface draait?

Nee. De MCP-server praat met de interne Fava-API die wordt beheerd door de infrastructuur van Web Beancount (Fava is de webinterface die je beancount.io-grootboek aandrijft). Je hoeft de Fava-UI niet open of toegankelijk te hebben.

Wat gebeurt er als ik mijn MCP-toegang intrek?

Lopende MCP-sessies ontvangen 401-fouten bij de volgende tool-aanroep. Clients die OAuth 2.1 ondersteunen, proberen automatisch opnieuw te autoriseren en vragen je om opnieuw in te loggen.

Onder de motorkap

Voor de technisch nieuwsgierigen — hoe de server is gebouwd.

Waarom MCP in plaats van een eigen API/plugin per AI-tool bouwen?

MCP is de opkomende standaard en wordt al ondersteund door alle grote AI-editors. Het bouwen van één conforme MCP-server geeft ons in één keer compatibiliteit met het hele ecosysteem, versus het onderhouden van aparte integraties voor Claude, Cursor, Windsurf en wat er volgend kwartaal ook uitkomt. Het protocol regelt discovery, tool-schema's en streaming — wij richten ons op de domeinlogica.

Waarom OAuth 2.1 in plaats van statische API-sleutels?

OAuth 2.1 met PKCE is wat de MCP-specificatie aanbeveelt voor externe servers, en het is wat clients zoals Claude Code native implementeren. Het praktische voordeel: gebruikers raken nooit een token aan. De client ontdekt de autorisatieserver via ons .well-known/oauth-protected-resource-metadata-endpoint, voltooit PKCE en beheert de vernieuwing automatisch. Statische tokens blijven ondersteund als terugvaloptie voor clients die de volledige flow nog niet hebben geïmplementeerd.

Waarom Streamable HTTP in plaats van SSE- of stdio-transport?

Streamable HTTP is het MCP-transport dat is ontworpen voor externe servers over HTTPS. Stdio is voor lokale processen. SSE (het oudere MCP-transport) wordt uitgefaseerd ten gunste van Streamable HTTP. Onze gebruikers verbinden vanuit AI-clients die niet co-located zijn met onze server, dus Streamable HTTP is de juiste en toekomstgerichte keuze.

Waarom is de MCP-sessie stateless (geen sessionIdGenerator)?

We stellen sessionIdGenerator: undefined in om elke aanvraag volledig stateless te maken — er wordt geen server-side sessiestatus toegewezen of behouden tussen tool-aanroepen. Dit komt overeen met de stateless modus van de Streamable HTTP-specificatie en houdt de server horizontaal schaalbaar zonder session affinity. De tool-context (grootboekidentiteit, Fava-API-client) wordt per aanvraag gereconstrueerd uit het gevalideerde OIDC-token.

Hoe werkt de verificatie van grootboektoegang?

Na validatie van het OIDC-token controleert resolveLedgerAccess via de Fava-API of de geauthenticeerde gebruiker daadwerkelijk toegang heeft tot het gevraagde grootboek. Dit voorkomt dat een geldig token voor één grootboek wordt gebruikt om het grootboek van een andere gebruiker te onderzoeken (defense-in-depth bovenop het ondertekende token).

Waar legt editLedgerFiles naartoe vast?

Het roept changeLedgerFiles aan op de Fava-API, die een git-commit aanmaakt in de Gitea-repository van het grootboek met het bericht AI edit: <description>. De beschrijving komt uit het description-veld dat de AI invult — getoond aan de gebruiker in goed-gedragende MCP-clients vóór uitvoering.

Wat is de dry_run-optie op editLedgerFiles?

dry_run: true valideert alle bestandsbewerkingen (controleert of bestanden bestaan, verifieert dat de oude strings van str_replace exact één keer overeenkomen) en geeft een voorbeeld terug van wat er zou worden vastgelegd — zonder daadwerkelijk naar git te schrijven. Dit is handig voor AI-clients die de gebruiker een diff willen tonen voordat ze vastleggen.

Wat is het foutoppervlak dat zichtbaar is voor AI-clients?

Tool-fouten worden geretourneerd als { isError: true, content: [{ type: "text", text: "..." }] } — het gestructureerde foutformaat van de MCP-SDK. De AI-client ontvangt het foutbericht als tekst en kan bepalen hoe ermee om te gaan (opnieuw proberen, aan de gebruiker melden, enz.). Auth-fouten op HTTP-niveau (401) bevatten een WWW-Authenticate-header die verwijst naar de OAuth protected resource-metadata, zodat conforme clients de autorisatieflow automatisch opnieuw kunnen starten.