# Beancount MCP: connecta el teu llibre de comptes amb assistents d'IA

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.

![Un ordinador portàtil d'argila connectat a un llibre de comptes verd obert, amb un rebut en una safata de revisió i blocs enllaçats que representen l'historial de Git.](/img/blog/beancount-mcp/hero.webp)

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:

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

### Claude Code

Afegeix el servidor des del teu terminal:

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

Obre 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](https://code.claude.com/docs/en/mcp) 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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### Cursor

Afegeix el servidor al teu `~/.cursor/mcp.json` personal:

```json
{
  "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](https://cursor.com/docs/mcp) 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](https://beancount.io/settings/api-keys). **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:Cash` i categoritzada a `Expenses:Food`. Comprova que aquests comptes existeixin i busca primer una transacció coincident. Utilitza `appendLedgerText` amb `dry_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í:

```beancount
2026-09-15 * "Cafe" "Cafè"
  Expenses:Food   4.50 USD
  Assets:Cash    -4.50 USD
```

Utilitza noms de compte del teu propi llibre i després completa la revisió:

1. Comprova la data, l'import, els comptes i el fitxer de destinació a la previsualització.
2. Confirma el canvi exacte que vols que l'assistent apliqui.
3. Demana-li que executi `checkLedger` i que informi del commit resultant i de qualsevol error.

`appendLedgerText` rebutja nous errors de validació per defecte. Els canvis generals de fitxers utilitzen `createLedgerFiles`, `updateLedgerFiles` i `deleteLedgerFiles`, cadascuna de les quals desa els seus 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.
