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.
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 è:
https://beancount.io/api-gateway/mcpClaude Code
Aggiungi il server dal tuo terminale:
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpApri 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 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.
Cursor
Aggiungi il server al tuo ~/.cursor/mcp.json personale:
{
"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 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. 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:Cashe categorizzato sottoExpenses:Food. Controlla che quei conti esistano e cerca prima una transazione corrispondente. UsaappendLedgerTextcondry_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:
2026-09-15 * "Cafe" "Coffee"
Expenses:Food 4.50 USD
Assets:Cash -4.50 USDUsa i nomi dei conti dal tuo registro, poi completa la revisione:
- Controlla data, importo, conti e file di destinazione nell'anteprima.
- Conferma la modifica esatta che vuoi che l'assistente applichi.
- Chiedigli di eseguire
checkLedgere di segnalare il commit risultante e eventuali errori.
appendLedgerText rifiuta nuovi errori di validazione per impostazione predefinita. Le modifiche generali ai file usano editLedgerFiles, che può creare, sostituire, aggiornare o eliminare file in un singolo commit Git. La sua 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.
