Pregunta al teu assistent d'IA quant vas gastar el mes passat, quins comptes calen reconciliar o on pertany una transacció. Beancount MCP li dona accés a les consultes, comptes i fitxers font del teu llibre de comptes allotjat, de manera que pot treballar a partir dels teus llibres i mostrar l'evidència que hi ha darrere de les seves respostes.
Amb permís d'escriptura, l'assistent també pot afegir transaccions i actualitzar fitxers del llibre. Pots demanar-li que previsualitzi les edicions admeses, que revisi les entrades proposades i que comprovi el llibre després d'un canvi.
MCP significa Model Context Protocol: un estàndard per connectar aplicacions d'IA a eines i dades externes. Aquesta connexió funciona amb llibres de comptes allotjats a Beancount.io. Les respostes del teu assistent reflecteixen les transaccions i els preus registrats allà; connectar MCP no fa que aquests registres estiguin automàticament actualitzats.
Connecta el teu client d'IA
Utilitza un client que admeti MCP remot sobre Streamable HTTP. L'URL del servidor és:
https://beancount.io/api-gateway/mcpClaude Code
Afegeix el servidor des del teu terminal:
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpObre Claude Code, executa /mcp, selecciona beancount i segueix el seu flux d'autenticació. Inicia sessió a Beancount.io i revisa els permisos sol·licitats. Torna a /mcp per confirmar la connexió. Consulta les instruccions MCP de Claude Code per a detalls específics del client.
La pàgina de consentiment et permet restringir l'accés a un llibre de comptes o triar explícitament Tots els llibres de comptes accessibles. Una restricció a un sol llibre és un bon punt de partida. Amb accés més ampli, digues a l'assistent quin llibre utilitzar, com ara alice/personal; les eines del llibre han d'identificar el seu objectiu en cada crida.
Claude Desktop i Claude al web
Obre Personalitza → Connectors, tria Afegeix connector personalitzat, introdueix l'URL del servidor i connecta el teu compte de Beancount.io. Activa el connector per a la conversa on el vulguis utilitzar. Els comptes d'organització poden necessitar que un propietari afegeixi primer el connector. Segueix la guia de connectors remots de Claude.
Cursor
Afegeix el servidor al teu ~/.cursor/mcp.json personal:
{
"mcpServers": {
"beancount": {
"url": "https://beancount.io/api-gateway/mcp"
}
}
}Completa l'inici de sessió OAuth quan Cursor ho sol·liciti i, després, comprova que les eines del servidor estiguin disponibles. La documentació MCP de Cursor cobreix la configuració i la configuració d'aprovació d'eines.
Claus API personals
Per a un client que accepti credencials bearer, pots crear una clau API personal a Configuració → Tokens d'accés personal. Crear una clau requereix un pla de pagament de Beancount.io. Selecciona ledger.read per a consultes, opcionalment restringeix la clau a un llibre de comptes i copia-la quan es mostri. Configura la capçalera d'autorització del teu client com Authorization: Bearer LA_TEUA_CLAU mitjançant la seva configuració de credencials privades.
Mantén la clau fora de la configuració compartida del projecte. Els clients OAuth gestionen les credencials a través del seu flux d'inici de sessió; no cal crear una clau personal per a aquesta via.
Comença amb una pregunta sobre despeses
Prova això després de connectar-te, substituint el nom del llibre pel teu:
Utilitza
alice/personal. Identifica els seus comptes i monedes, i després resumeix les despeses d'agost de 2026 per compte. Mostra el rang de dates i la BQL darrere de cada total, mantén les monedes separades i informa de qualsevol error de validació del llibre. No canviïs res.
L'assistent pot descobrir els teus llibres amb listLedgers, aprendre els noms dels teus comptes mitjançant getLedgerContext i executar runBqlQueryStructured per a resultats de consulta tipats. checkLedger retorna errors de validació, recomptes d'entrades i l'últim commit.
Una resposta útil inclou el llibre, el període, les monedes, els totals i les consultes de suport. Per a una pregunta de patrimoni net, demana també el mètode de valoració i les dates dels preus utilitzats. Les transaccions que falten o els preus obsolets poden canviar la resposta fins i tot quan el llibre passa la validació.
Afegeix una transacció amb previsualització
Per a entrades noves, appendLedgerText accepta text Beancount normal i dirigeix les directives a fitxers utilitzant la configuració del teu llibre. La seva opció dry_run retorna un diff i errors de validació projectats abans de confirmar.
Per exemple:
Prepara una compra de cafè de 4,50 USD amb data 15 de setembre de 2026, pagada des de
Assets:Cashi categoritzada aExpenses:Food. Comprova que aquests comptes existeixin i busca primer una transacció coincident. UtilitzaappendLedgerTextambdry_run: true, mostra l'entrada proposada i el diff del fitxer, i espera la meva confirmació.
Amb aquests comptes ja oberts, l'entrada proposada seria així:
2026-09-15 * "Cafe" "Cafè"
Expenses:Food 4.50 USD
Assets:Cash -4.50 USDUtilitza noms de compte del teu propi llibre i després completa la revisió:
- Comprova la data, l'import, els comptes i el fitxer de destinació a la previsualització.
- Confirma el canvi exacte que vols que l'assistent apliqui.
- Demana-li que executi
checkLedgeri que informi del commit resultant i de qualsevol error.
appendLedgerText rebutja nous errors de validació per defecte. Els canvis generals de fitxers utilitzen editLedgerFiles, que pot crear, substituir, actualitzar o suprimir fitxers en un sol commit de Git. La seva previsualització també informa d'un diff i d'errors projectats. Comprova el resultat i executa checkLedger després d'escriure: un commit reeixit encara pot contenir errors comptables.
Utilitza un flux de treball per a la comptabilitat recurrent
El servidor també proporciona indicacions MCP reutilitzables. Els clients amb suport d'indicacions les exposen al seu selector d'ordres o indicacions:
| Flux de treball | Per a què t'ajuda |
|---|---|
spending-report | Respondre una pregunta sobre despeses amb BQL de suport i sense escriptures al llibre. |
reconcile-account | Comparar un compte amb un extracte proporcionat, classificar diferències i proposar entrades que falten. |
close-month | Revisar comptes actius, afirmacions de saldo, transaccions recurrents i indicadors sense resoldre. |
categorize-imports | Revisar transaccions bancàries en preparació i proposar categories utilitzant comptes existents. |
Aquestes indicacions guien l'assistent a través d'un procediment. No executen una tasca comptable simplement perquè les seleccionis, i no atorguen permisos addicionals.
La reconciliació necessita un extracte i un saldo final. Un resultat de validació net per si sol no pot establir que s'hagi registrat cada transacció. Demana a l'assistent que identifiqui qualsevol cosa que no hagi pogut verificar i deixa aquestes preguntes visibles a l'informe.
Per a importacions bancàries, primer enllaça el banc a Beancount.io. Llegir els detalls de connexió requereix accés administratiu; enviar transaccions en preparació requereix permís d'escriptura i l'accés adequat a aquesta connexió bancària. Revisa les categories i duplicats proposats abans d'autoritzar l'enviament.
Entén l'accés i la gestió de dades
Els permisos de la connexió determinen què pot fer l'assistent:
| Permís | Accés |
|---|---|
ledger.read | Consultar i llegir dades del llibre. |
ledger.write | Llegir dades i fer canvis ordinaris al llibre. |
ledger.admin | Llegir, escriure i realitzar operacions administratives allà on estigui autoritzat. |
El teu accés existent a cada llibre encara s'aplica. Restringir una credencial a un llibre impedeix que les crides del llibre es dirigeixin a un altre; una credencial sense restriccions pot seleccionar entre els llibres als quals tens accés. El client OAuth tria quins permisos sol·licitar, així que llegeix la pantalla de consentiment abans d'aprovar.
El servidor MCP no mostra un diàleg d'aprovació humana. La configuració del teu client determina quan demana abans de cridar una eina, i les previsualitzacions s'han de sol·licitar explícitament. Els fluxos de treball d'escriptura proporcionats instrueixen l'assistent a esperar confirmació. Una credencial restringida a ledger.read proporciona una frontera forçada quan vols anàlisi sense escriptures.
Els resultats de les eines, incloses les transaccions consultades i els fitxers que l'assistent llegeix, entren al context del teu client d'IA i poden ser processats pel seu proveïdor de models. Beancount.io conserva el teu llibre, l'historial de Git i els registres operatius. Una connexió MCP sense estat no és una promesa que no es conservin dades; les polítiques de dades del teu client i del seu proveïdor també s'apliquen.
Les claus API personals revocades es rebutgen en sol·licituds posteriors. Els tokens d'accés OAuth normalment duren una hora; revocar un token de refresc no invalida immediatament un token d'accés ja emès. L'accés al llibre es comprova de nou quan s'executen operacions protegides.
Preguntes habituals
Això obre el llibre al meu ordinador portàtil?
L'endpoint allotjat opera al teu llibre de Beancount.io. No obre cap fitxer .bean local, i no necessites tenir una pestanya del navegador de Fava oberta.
En què es diferencia de l'assistent d'IA del tauler de control?
El tauler de control proporciona la seva pròpia interfície de xat. MCP fa disponibles les capacitats del llibre des d'un client d'IA extern, amb la conversa, el model i la configuració d'aprovació d'aquest client.
Per què puc veure una eina però no puc utilitzar-la?
El catàleg d'eines inclou operacions que la teva credencial pot no permetre. Comprova l'error i els permisos concedits. Una credencial sense restriccions també necessita un objectiu de llibre explícit per a les eines del llibre.
Connecta el teu llibre i comença amb una pregunta que puguis verificar amb els teus llibres. Conserva la consulta amb la resposta i, després, afegeix permisos d'escriptura quan vulguis ajuda per mantenir el llibre mateix.
