# Beancount MCP: collega il tuo registro agli assistenti AI

Chiedi al tuo assistente AI quanto hai speso il mese scorso, quali conti devono essere riconciliati o dove appartiene una transazione. Beancount MCP gli dà accesso a query, conti e file sorgente del tuo registro ospitato, così può lavorare sui tuoi libri contabili e mostrare le prove alla base della sua risposta.

![Un laptop di argilla collegato a un registro verde aperto, con una ricevuta in un vassoio di revisione e blocchi collegati che rappresentano la storia di Git.](/img/blog/beancount-mcp/hero.webp)

Con il permesso di scrittura, l'assistente può anche aggiungere transazioni e aggiornare i file del registro. Puoi chiedergli di visualizzare in anteprima le modifiche supportate, rivedere le voci proposte e controllare il registro dopo una modifica.

MCP sta per Model Context Protocol: uno standard per collegare applicazioni AI a strumenti e dati esterni. Questa connessione funziona con i registri ospitati su **Beancount.io**. Le risposte del tuo assistente riflettono le transazioni e i prezzi registrati lì; collegare MCP non rende automaticamente aggiornati quei dati.

## Collega il tuo client AI

Usa un client che supporti MCP remoto su **Streamable HTTP**. L'URL del server è:

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

### Claude Code

Aggiungi il server dal tuo terminale:

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

Apri Claude Code, esegui `/mcp`, seleziona `beancount` e segui il suo flusso di autenticazione. Accedi a Beancount.io e rivedi le autorizzazioni richieste. Torna a `/mcp` per confermare la connessione. Consulta le [istruzioni MCP di Claude Code](https://code.claude.com/docs/en/mcp) per i dettagli specifici del client.

La pagina di consenso ti consente di limitare l'accesso a **un registro** o di scegliere esplicitamente **Tutti i registri accessibili**. Una restrizione a un singolo registro è un utile punto di partenza. Con un accesso più ampio, indica all'assistente quale registro usare, ad esempio `alice/personal`; gli strumenti del registro devono identificare il loro obiettivo in ogni chiamata.

### Claude Desktop e Claude sul web

Apri **Personalizza → Connettori**, scegli **Aggiungi connettore personalizzato**, inserisci l'URL del server e collega il tuo account Beancount.io. Abilita il connettore per la conversazione in cui vuoi usarlo. Gli account organizzativi potrebbero richiedere che un proprietario aggiunga prima il connettore. Segui la [guida ai connettori remoti di Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### Cursor

Aggiungi il server al tuo `~/.cursor/mcp.json` personale:

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

Completa l'accesso OAuth quando Cursor lo richiede, poi verifica che gli strumenti del server siano disponibili. La [documentazione MCP di Cursor](https://cursor.com/docs/mcp) copre la configurazione e le impostazioni di approvazione degli strumenti.

### Chiavi API personali

Per un client che accetta credenziali bearer, puoi creare una chiave API personale in [Impostazioni → Token di accesso personale](https://beancount.io/settings/api-keys). **La creazione di una chiave richiede un piano Beancount.io a pagamento.** Seleziona `ledger.read` per le query, limita facoltativamente la chiave a un registro e copiala quando viene mostrata. Configura l'intestazione di autorizzazione del tuo client come `Authorization: Bearer YOUR_KEY` usando le sue impostazioni delle credenziali private.

Tieni la chiave fuori dalla configurazione di progetto condivisa. I client OAuth gestiscono le credenziali tramite il loro flusso di accesso; non è necessario creare una chiave personale per quel percorso.

## Inizia con una domanda sulle spese

Prova questo dopo la connessione, sostituendo il nome del registro con il tuo:

> Usa `alice/personal`. Identifica i suoi conti e le sue valute, poi riepiloga le spese di agosto 2026 per conto. Mostra l'intervallo di date e la BQL dietro ogni totale, tieni separate le valute e segnala eventuali errori di validazione del registro. Non modificare nulla.

L'assistente può scoprire i tuoi registri con `listLedgers`, apprendere i nomi dei tuoi conti tramite `getLedgerContext` ed eseguire `runBqlQueryStructured` per risultati di query tipizzati. `checkLedger` restituisce errori di validazione, conteggi delle voci e l'ultimo commit.

Una risposta utile include il registro, il periodo, le valute, i totali e le query di supporto. Per una domanda sul patrimonio netto, chiedi anche il metodo di valutazione e le date dei prezzi utilizzati. Transazioni mancanti o prezzi obsoleti possono cambiare la risposta anche quando il registro supera la validazione.

## Aggiungi una transazione con un'anteprima

Per nuove voci, `appendLedgerText` accetta testo Beancount ordinario e instrada le direttive ai file usando la configurazione del tuo registro. La sua opzione `dry_run` restituisce un diff e gli errori di validazione previsti prima del commit.

Ad esempio:

> Prepara un acquisto di caffè da 4,50 USD datato 15 settembre 2026, pagato da `Assets:Cash` e categorizzato sotto `Expenses:Food`. Controlla che quei conti esistano e cerca prima una transazione corrispondente. Usa `appendLedgerText` con `dry_run: true`, mostra la voce proposta e il diff del file, e attendi la mia conferma.

Con quei conti già aperti, la voce proposta sarebbe simile a questa:

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

Usa i nomi dei conti dal tuo registro, poi completa la revisione:

1. Controlla data, importo, conti e file di destinazione nell'anteprima.
2. Conferma la modifica esatta che vuoi che l'assistente applichi.
3. Chiedigli di eseguire `checkLedger` e di segnalare il commit risultante e eventuali errori.

`appendLedgerText` rifiuta nuovi errori di validazione per impostazione predefinita. Le modifiche generali ai file usano `createLedgerFiles`, `updateLedgerFiles` e `deleteLedgerFiles`, ognuno dei quali salva i propri file in un singolo commit Git. La loro anteprima segnala anche un diff ed errori previsti. Controlla il risultato ed esegui `checkLedger` dopo la scrittura: un commit riuscito può ancora contenere errori contabili.

## Usa un flusso di lavoro per la contabilità ricorrente

Il server fornisce anche prompt MCP riutilizzabili. I client con supporto ai prompt li espongono nel loro selettore di comandi o prompt:

| Flusso di lavoro | A cosa ti aiuta |
| --- | --- |
| `spending-report` | Rispondere a una domanda sulle spese con BQL di supporto e nessuna scrittura sul registro. |
| `reconcile-account` | Confrontare un conto con un estratto conto fornito, classificare le differenze e proporre voci mancanti. |
| `close-month` | Rivedere conti attivi, verifiche di saldo, transazioni ricorrenti e flag non risolti. |
| `categorize-imports` | Rivedere transazioni bancarie in coda e proporre categorie usando i conti esistenti. |

Questi prompt guidano l'assistente attraverso una procedura. Non eseguono un lavoro contabile semplicemente perché li selezioni e non concedono autorizzazioni aggiuntive.

La riconciliazione richiede un estratto conto e un saldo finale. Un risultato di validazione pulito da solo non può stabilire che ogni transazione sia stata registrata. Chiedi all'assistente di identificare tutto ciò che non ha potuto verificare e lascia quelle domande visibili nel rapporto.

Per le importazioni bancarie, collega prima la banca in Beancount.io. La lettura dei dettagli di connessione richiede accesso amministrativo; l'invio di transazioni in coda richiede permesso di scrittura e l'accesso appropriato a quella connessione bancaria. Rivedi le categorie e i duplicati proposti prima di autorizzare l'invio.

## Comprendi accesso e gestione dei dati

Le autorizzazioni della connessione determinano cosa può fare l'assistente:

| Autorizzazione | Accesso |
| --- | --- |
| `ledger.read` | Interrogare e leggere i dati del registro. |
| `ledger.write` | Leggere i dati e apportare modifiche ordinarie al registro. |
| `ledger.admin` | Leggere, scrivere ed eseguire operazioni amministrative dove autorizzato. |

Il tuo accesso esistente a ogni registro rimane valido. Limitare una credenziale a un registro impedisce alle chiamate del registro di prendere di mira un altro; una credenziale illimitata può selezionare tra i registri a cui hai accesso. Il client OAuth sceglie quali autorizzazioni richiedere, quindi leggi la schermata di consenso prima di approvare.

**Il server MCP non mostra una finestra di approvazione umana.** Le impostazioni del tuo client determinano quando chiede prima di chiamare uno strumento e le anteprime devono essere richieste esplicitamente. I flussi di lavoro di scrittura forniti istruiscono l'assistente ad attendere conferma. Una credenziale limitata a `ledger.read` fornisce un confine applicato quando vuoi analisi senza scritture.

I risultati degli strumenti, incluse le transazioni interrogate e i file che l'assistente legge, entrano nel contesto del tuo client AI e possono essere elaborati dal suo fornitore di modelli. Beancount.io conserva il tuo registro, la storia Git e i record operativi. Una connessione MCP senza stato non è una promessa che nessun dato venga conservato; si applicano anche le politiche sui dati del tuo client e del suo fornitore.

Le chiavi API personali revocate vengono rifiutate nelle richieste successive. I token di accesso OAuth durano normalmente un'ora; revocare un token di aggiornamento non invalida immediatamente un token di accesso già emesso. L'accesso al registro viene ricontrollato quando vengono eseguite operazioni protette.

## Domande comuni

**Questo apre il registro sul mio laptop?**

L'endpoint ospitato opera sul tuo registro Beancount.io. Non apre un file `.bean` locale e non hai bisogno di una scheda del browser Fava aperta.

**In cosa è diverso dall'assistente AI della dashboard?**

La dashboard fornisce la propria interfaccia chat. MCP rende disponibili le capacità del registro da un client AI esterno, con le impostazioni di conversazione, modello e approvazione di quel client.

**Perché posso vedere uno strumento ma non posso usarlo?**

Il catalogo degli strumenti include operazioni che la tua credenziale potrebbe non consentire. Controlla l'errore e le autorizzazioni concesse. Una credenziale illimitata richiede anche un target di registro esplicito per gli strumenti del registro.

Collega il tuo registro e inizia con una domanda che puoi verificare nei tuoi libri. Conserva la query con la risposta, poi aggiungi i permessi di scrittura quando vuoi aiuto per mantenere il registro stesso.
