Beancount MCP: connecta el teu llibre major a Claude, Cursor i qualsevol assistent d'IA

Web Beancount llança el servidor MCP — Parla amb el teu llibre major des de Claude, Cursor i qualsevol eina d'IA que ja utilitzis

Les teves dades comptables es troben amb el teu flux de treball d'IA. Sense copiar i enganxar. Sense exportacions. Només pregunta.

Avui, Web Beancount anuncia el servidor Beancount MCP — un punt de connexió del Model Context Protocol (MCP) que et permet connectar el teu llibre major de Beancount directament amb Claude Desktop, Claude Code, Cursor, Windsurf o qualsevol altre client d'IA compatible amb MCP. Per primera vegada, els usuaris avançats poden fer preguntes de comptabilitat, executar consultes BQL i fins i tot editar fitxers del llibre major des de dins de les eines d'IA on ja treballen — sense canviar de pestanya ni sortir del seu flux de treball.

Els fitxers de Beancount en text pla són potents precisament perquè només són fitxers. Però respondre "quant vaig gastar en viatges el trimestre passat?" encara requereix conèixer la sintaxi BQL, saber on són els teus fitxers i copiar els resultats en un xat. El servidor Beancount MCP elimina completament aquesta fricció.

Amb el servidor Beancount MCP configurat al teu client d'IA, pots:

Preguntar "Quin és el meu patrimoni net avui?" i obtenir una resposta en directe extreta del teu llibre major real
Sol·licitar un resum de les despeses del mes passat i fer que la IA escrigui la consulta BQL per tu
Dir a la IA que afegeixi una transacció i veure com confirma el canvi al repositori git del teu llibre major
Navegar i llegir els teus fitxers .beancount sense sortir mai del teu editor

El servidor està limitat per llibre major: cada sessió MCP està autoritzada per a exactament un llibre major mitjançant OAuth 2.1. Clients com Claude Code descobreixen i completen el flux d'autorització automàticament — no cal gestionar tokens manualment. El teu llibre major es queda on ja viu, al backend de Web Beancount: el client d'IA envia crides d'eina estructurades al nostre servidor, que llegeix o edita el teu llibre major en nom teu i retorna els resultats. El servidor MCP en si mateix no emmagatzema res més enllà del que conté la conversa del teu propi client d'IA.

El servidor Beancount MCP està disponible avui per a tots els usuaris de Web Beancount.

Comença

El servidor Beancount MCP està en funcionament. Afegeix-lo al teu client d'IA en menys d'un minut.

URL del servidor MCP

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

Claude Code (recomanat — flux OAuth 2.1 complet, sense necessitat de token)

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

En el primer ús, Claude Code obrirà una finestra del navegador. L'avís del navegador és on tries quin llibre major vols connectar — aprova'l un cop, i les credencials es renoven automàticament. Tens més d'un llibre major? Afegeix el servidor de nou amb un nom diferent (claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp) i autoritza l'altre llibre major al seu propi avís.

Claude Desktop / Cursor / Windsurf / Zed

Afegeix el servidor a la configuració MCP del teu client (claude_desktop_config.json o equivalent). Els clients compatibles amb OAuth 2.1 obren el mateix avís del navegador en el primer ús — tria el teu llibre major allà:

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

Si el teu client encara no és compatible amb el flux OAuth, genera un token estàtic (limitat a un llibre major) des de la configuració del teu compte de beancount.io i passa'l com a capçalera:

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

No tens un compte de Web Beancount? Registra't a beancount.io — el teu llibre major és a un git push de distància.

Preguntes freqüents

Preguntes freqüents dels clients

Què és MCP i per què és important per a Beancount?

MCP (Model Context Protocol) és un estàndard obert que permet als assistents d'IA cridar eines i fonts de dades externes d'una manera estructurada i segura. Pensa-hi com un port USB per a la IA: en lloc que la IA endevini o et demani que enganxis dades, es connecta directament als teus sistemes. Per als usuaris de Beancount, això vol dir que el teu client d'IA pot consultar les dades reals del teu llibre major, llegir els teus fitxers reals i fer edicions precises — no endevinar què podrien contenir.

Quins clients d'IA funcionen amb el servidor Beancount MCP?

Qualsevol client compatible amb MCP que admeti OAuth 2.1 funciona directament. El servidor Beancount MCP implementa el flux complet d'autorització OAuth 2.1 amb PKCE, de manera que clients com Claude Code descobriran automàticament el punt d'autorització del servidor i et demanaran que iniciïs sessió — sense copiar tokens manualment ni configurar res. Un cop aprovis l'accés, el client emmagatzema i renova les credencials automàticament.

Els clients amb compatibilitat coneguda amb MCP + OAuth 2.1 inclouen Claude Code CLI, Claude Desktop, Cursor, Windsurf i Zed. A mesura que l'ecosistema MCP creixi, qualsevol client nou que segueixi l'especificació MCP d'OAuth 2.1 funcionarà sense canvis per la nostra banda.

Com connecto el meu llibre major?

Per a clients compatibles amb OAuth 2.1 (com Claude Code):

Afegeix l'URL del servidor Beancount MCP a la configuració MCP del teu client.
El client obre automàticament una finestra del navegador per autoritzar l'accés.
Inicia sessió amb el teu compte de Web Beancount i tria el llibre major al qual vols atorgar accés.
Fet — el client s'encarrega de l'emmagatzematge i la renovació del token a partir d'aquí.

Per a clients sense compatibilitat amb OAuth 2.1, genera un token estàtic (limitat a un llibre major) des de la configuració del teu compte de Web Beancount i passa'l com a capçalera Authorization: Bearer.

És el mateix que la funció de xat "Ask AI" del tauler de control?

Comparteixen les mateixes eines subjacents del llibre major (consultes BQL, lectura/escriptura de fitxers), però el servidor MCP és un punt d'entrada diferent. La funció Ask AI del tauler de control és una experiència de xat allotjada amb un entorn aïllat de Claude Code recolzat per Cloudflare. El servidor MCP és un punt de connexió de protocol al qual et connectes des del teu propi client d'IA preferit — cosa que et dóna més control, més models i una integració més profunda amb el teu flux de treball existent.

Què pot fer realment la IA amb el meu llibre major?

El servidor MCP exposa quatre eines:

Eina	Què fa
`runBqlQuery`	Executa BQL (Beancount Query Language) per consultar saldos, transaccions i comptes
`listLedgerFiles`	Navega per l'estructura de directoris del repositori del teu llibre major
`readLedgerFiles`	Llegeix el contingut dels fitxers `.beancount` i altres documents del llibre major
`editLedgerFiles`	Crea, actualitza, reemplaça o elimina fitxers en una confirmació git atòmica

La IA les pot combinar: descobrir l'estructura dels teus fitxers, llegir els fitxers rellevants per obtenir context, escriure una consulta BQL per respondre la teva pregunta, o proposar i confirmar una edició.

Pot la IA modificar el meu llibre major sense que jo ho sàpiga?

Les edicions de fitxers requereixen que el client d'IA cridi editLedgerFiles amb una descripció del que està canviant. Els clients MCP ben construïts (inclòs Claude Code) t'ho mostren abans d'executar-ho. Les edicions també admeten un mode dry_run que previsualitza els canvis exactes sense escriure res, de manera que el teu client et pot mostrar primer una diferència. I cada canvi confirmat és una confirmació git real al repositori del teu llibre major, així que tens un rastre d'auditoria complet i pots revertir qualsevol cosa amb les eines git estàndard.

S'envien les meves dades a un tercer?

Les dades del teu llibre major flueixen a través del backend de Web Beancount (que ja gestiona el teu llibre major) i es retornen com a resultats estructurats al teu client d'IA. El model d'IA que utilitzes (per exemple, Claude) rep els resultats de l'eina com qualsevol altre context. El servidor MCP no emmagatzema cap dada més enllà del que ja conté la conversa del teu client d'IA.

Cada token està limitat a un llibre major — què vol dir això?

Quan autoritzes el servidor MCP, tries a quin llibre major vols atorgar accés. Aquesta sessió només pot accedir a aquest llibre major. Si tens múltiples llibres majors, autoritzes sessions separades. Això limita el radi d'impacte: una sessió per al teu llibre major personal no pot tocar el teu llibre major d'empresa.

El servidor MCP requereix que la interfície web de Fava estigui en funcionament?

No. El servidor MCP es comunica amb l'API interna de Fava gestionada per la infraestructura de Web Beancount (Fava és la interfície web que impulsa el teu llibre major de beancount.io). No cal que tinguis la interfície de Fava oberta ni accessible.

Què passa si revoco el meu accés MCP?

Les sessions MCP en curs rebran errors 401 en la següent crida d'eina. Els clients compatibles amb OAuth 2.1 intentaran tornar a autoritzar-se automàticament, demanant-te que iniciïs sessió de nou.

Per dins

Per als tècnicament curiosos — com està construït el servidor.

Per què MCP en lloc de construir la nostra pròpia API/connector per a cada eina d'IA?

MCP és l'estàndard emergent i ja compatible amb tots els principals editors d'IA. Construir un servidor MCP compatible ens dóna compatibilitat amb tot l'ecosistema de cop, en lloc de mantenir integracions separades per a Claude, Cursor, Windsurf i el que surti el proper trimestre. El protocol s'encarrega del descobriment, els esquemes d'eines i el streaming — nosaltres ens centrem en la lògica del domini.

Per què OAuth 2.1 en lloc de claus d'API estàtiques?

OAuth 2.1 amb PKCE és el que recomana l'especificació MCP per a servidors remots, i és el que clients com Claude Code implementen de manera nativa. El benefici pràctic: els usuaris mai no toquen un token. El client descobreix el servidor d'autorització mitjançant el nostre punt de metadades .well-known/oauth-protected-resource, completa PKCE i gestiona la renovació automàticament. Els tokens estàtics continuen sent compatibles com a alternativa per als clients que no han implementat el flux complet.

Per què Streamable HTTP en lloc del transport SSE o stdio?

Streamable HTTP és el transport MCP dissenyat per a servidors remots sobre HTTPS. Stdio és per a processos locals. SSE (el transport MCP més antic) s'està desestimant a favor de Streamable HTTP. Els nostres usuaris es connecten des de clients d'IA que no estan ubicats junts amb el nostre servidor, així que Streamable HTTP és l'elecció correcta i orientada al futur.

Per què la sessió MCP és sense estat (sense sessionIdGenerator)?

Establim sessionIdGenerator: undefined per fer que cada sol·licitud sigui completament sense estat — no s'assigna ni es reté cap estat de sessió al servidor entre les crides d'eina. Això coincideix amb el mode sense estat de l'especificació de Streamable HTTP i manté el servidor escalable horitzontalment sense afinitat de sessió. El context de l'eina (identitat del llibre major, client de l'API de Fava) es reconstrueix per sol·licitud a partir del token OIDC validat.

Com funciona la verificació d'accés al llibre major?

Després de la validació del token OIDC, resolveLedgerAccess comprova mitjançant l'API de Fava que l'usuari autenticat realment té accés al llibre major sol·licitat. Això evita que un token vàlid per a un llibre major s'utilitzi per sondejar el llibre major d'un altre usuari (defensa en profunditat sobre el token signat).

On confirma els canvis editLedgerFiles?

Crida changeLedgerFiles a l'API de Fava, que crea una confirmació git al repositori Gitea del llibre major amb el missatge AI edit: <description>. La descripció prové del camp description que emplena la IA — mostrat a l'usuari en els clients MCP ben construïts abans de l'execució.

Què és l'opció dry_run a editLedgerFiles?

dry_run: true valida totes les operacions de fitxers (comprova que els fitxers existeixen, verifica que les cadenes originals de str_replace coincideixen exactament un cop) i retorna una previsualització del que es confirmaria — sense escriure realment a git. Això és útil per als clients d'IA que volen mostrar una diferència a l'usuari abans de confirmar.

Quina és la superfície d'errors visible per als clients d'IA?

Els errors de les eines es retornen com a { isError: true, content: [{ type: "text", text: "..." }] } — el format d'error estructurat del SDK de MCP. El client d'IA rep el missatge d'error com a text i pot decidir com gestionar-lo (reintentar, informar l'usuari, etc.). Els errors d'autenticació a nivell HTTP (401) inclouen una capçalera WWW-Authenticate que apunta a les metadades del recurs protegit d'OAuth, de manera que els clients compatibles poden reiniciar automàticament el flux d'autorització.