Web Beancount Lancia il Server MCP — Parla con il tuo Ledger da Claude, Cursor e Qualsiasi Strumento AI che Usi Già
I tuoi dati contabili incontrano il tuo flusso di lavoro AI. Nessun copia-incolla. Nessuna esportazione. Basta chiedere.
Oggi, Web Beancount annuncia il Beancount MCP Server — un endpoint Model Context Protocol (MCP) che ti permette di collegare il tuo ledger Beancount direttamente a Claude Desktop, Claude Code, Cursor, Windsurf o qualsiasi altro client AI compatibile MCP. Per la prima volta, gli utenti avanzati possono fare domande di contabilità, eseguire query BQL e persino modificare i file del ledger direttamente dagli strumenti AI che usano ogni giorno — senza cambiare scheda o abbandonare il proprio flusso di lavoro.
I file Beancount in testo semplice sono potenti proprio perché sono solo file. Ma rispondere a "quanto ho speso in viaggi l'ultimo trimestre?" richiede ancora di conoscere la sintassi BQL, sapere dove sono i tuoi file e copiare i risultati in una chat. Il server MCP Beancount elimina completamente questo attrito.
Con il server MCP Beancount configurato nel tuo client AI, puoi:
- Chiedere "Qual è il mio patrimonio netto oggi?" e ottenere una risposta in tempo reale tratta dal tuo ledger reale
- Richiedere un riepilogo delle spese del mese scorso e lasciare che l'IA scriva la query BQL per te
- Dire all'IA di aggiungere una transazione e vederla applicare la modifica al repository git del tuo ledger
- Sfogliare e leggere i tuoi file
.beancountsenza mai lasciare il tuo editor
Il server è limitato a un ledger: ogni sessione MCP è autorizzata per un singolo ledger utilizzando OAuth 2.1. Client come Claude Code scoprono e completano automaticamente il flusso di autorizzazione — nessuna gestione manuale dei token richiesta. Il tuo ledger rimane dove già si trova, sul backend di Web Beancount: il client AI invia chiamate a strumenti strutturati al nostro server, che legge o modifica il ledger per tuo conto e restituisce i risultati. Il server MCP stesso non memorizza nulla oltre a quanto già contenuto nella conversazione del tuo client AI.
Il server MCP Beancount è disponibile oggi per tutti gli utenti di Web Beancount.
Per Iniziare
Il server MCP Beancount è attivo. Aggiungilo al tuo client AI in meno di un minuto.
URL del server MCP
https://beancount.io/api-gateway/mcpClaude Code (consigliato — flusso OAuth 2.1 completo, nessun token necessario)
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpAl primo utilizzo, Claude Code aprirà una finestra del browser. Il prompt nel browser è dove scegli quale ledger connettere — approvi una volta e le credenziali si aggiornano automaticamente. Hai più di un ledger? Aggiungi di nuovo il server con un nome diverso (claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp) e autorizza l'altro ledger nel suo prompt dedicato.
Claude Desktop / Cursor / Windsurf / Zed
Aggiungi il server alla configurazione MCP del tuo client (claude_desktop_config.json o equivalente). I client con supporto OAuth 2.1 aprono lo stesso prompt del browser al primo utilizzo — scegli lì il tuo ledger:
{
"mcpServers": {
"beancount": {
"url": "https://beancount.io/api-gateway/mcp"
}
}
}Se il tuo client non supporta ancora il flusso OAuth, genera un token statico (limitato a un ledger) dalle impostazioni del tuo account beancount.io e passalo come header:
{
"mcpServers": {
"beancount": {
"url": "https://beancount.io/api-gateway/mcp",
"headers": { "Authorization": "Bearer <il-tuo-token>" }
}
}
}Non hai un account Web Beancount? Registrati su beancount.io — il tuo ledger è a un git push di distanza.
Domande Frequenti
FAQ per i Clienti
Cos'è MCP e perché è importante per Beancount?
MCP (Model Context Protocol) è uno standard aperto che permette agli assistenti AI di chiamare strumenti e fonti di dati esterni in modo strutturato e sicuro. Pensalo come una porta USB per l'AI: invece di far indovinare l'AI o chiederti di incollare dati, si connette direttamente ai tuoi sistemi. Per gli utenti Beancount, questo significa che il tuo client AI può interrogare i dati reali del tuo ledger, leggere i tuoi file effettivi e apportare modifiche precise — non indovinare cosa potrebbero contenere.
Quali client AI funzionano con il server MCP Beancount?
Qualsiasi client compatibile MCP che supporti OAuth 2.1 funziona immediatamente. Il server MCP Beancount implementa il flusso di autorizzazione OAuth 2.1 completo con PKCE, quindi client come Claude Code scopriranno automaticamente l'endpoint di autorizzazione del server e ti chiederanno di accedere — nessuna copia manuale di token o configurazione richiesta. Una volta approvato l'accesso, il client memorizza e aggiorna le credenziali automaticamente.
I client con supporto noto per MCP + OAuth 2.1 includono Claude Code CLI, Claude Desktop, Cursor, Windsurf e Zed. Man mano che l'ecosistema MCP cresce, qualsiasi nuovo client che segue le specifiche OAuth 2.1 MCP funzionerà senza modifiche da parte nostra.
Come collego il mio ledger?
Per i client che supportano OAuth 2.1 (come Claude Code):
- Aggiungi l'URL del server MCP Beancount alla configurazione MCP del tuo client.
- Il client apre automaticamente una finestra del browser per autorizzare l'accesso.
- Accedi con il tuo account Web Beancount e scegli il ledger a cui vuoi concedere l'accesso.
- Fatto — il client gestisce l'archiviazione e l'aggiornamento del token da qui in poi.
Per i client senza supporto OAuth 2.1, genera un token statico (limitato a un ledger) dalle impostazioni del tuo account Web Beancount e passalo come header Authorization: Bearer.
È la stessa funzione "Chiedi all'AI" nel cruscotto?
Condividono gli stessi strumenti di ledger sottostanti (query BQL, lettura/scrittura file), ma il server MCP è un punto di accesso diverso. La funzione Chiedi all'AI del cruscotto è un'esperienza di chat ospitata con una sandbox Claude Code basata su Cloudflare. Il server MCP è un endpoint di protocollo a cui ti colleghi dal tuo client AI di scelta — dandoti più controllo, più modelli e un'integrazione più profonda con il tuo flusso di lavoro esistente.
Cosa può fare effettivamente l'AI con il mio ledger?
Il server MCP espone quattro strumenti:
| Strumento | Cosa fa |
|---|---|
runBqlQuery | Esegue BQL (Beancount Query Language) per interrogare saldi, transazioni, conti |
listLedgerFiles | Sfoglia la struttura delle directory del tuo repository del ledger |
readLedgerFiles | Legge il contenuto dei file .beancount e altri documenti del ledger |
editLedgerFiles | Crea, aggiorna, sostituisce o elimina file in un commit git atomico |
L'AI può combinare questi strumenti: scoprire la struttura dei tuoi file, leggere i file rilevanti per il contesto, scrivere una query BQL per rispondere alla tua domanda, o proporre e confermare una modifica.
L'AI può modificare il mio ledger a mia insaputa?
Le modifiche ai file richiedono che il client AI chiami editLedgerFiles con una descrizione di ciò che sta cambiando. I client MCP ben educati (incluso Claude Code) ti mostrano queste modifiche prima di eseguirle. Le modifiche supportano anche una modalità dry_run che anteprime le modifiche esatte senza scrivere nulla, in modo che il tuo client possa mostrarti prima una differenza. E ogni modifica confermata è un vero commit git nel repository del tuo ledger, quindi hai una traccia di controllo completa e puoi annullare qualsiasi cosa con gli strumenti git standard.
I miei dati vengono inviati a terze parti?
I tuoi dati del ledger fluiscono attraverso il backend di Web Beancount (che già gestisce il tuo ledger) e vengono restituiti come risultati strutturati al tuo client AI. Il modello AI che usi (ad esempio, Claude) riceve i risultati degli strumenti come qualsiasi altro contesto. Nessun dato viene memorizzato dal server MCP oltre a quanto già contenuto nella conversazione del tuo client AI.
Ogni token è limitato a un ledger — cosa significa?
Quando autorizzi il server MCP, scegli a quale ledger concedere l'accesso. Quella sessione può accedere solo a quel ledger. Se hai più ledger, autorizzi sessioni separate. Questo limita il raggio d'azione: una sessione per il tuo ledger personale non può toccare il tuo ledger aziendale.
Il server MCP richiede che l'interfaccia web Fava sia in esecuzione?
No. Il server MCP comunica con l'API Fava interna gestita dall'infrastruttura di Web Beancount (Fava è l'interfaccia web che alimenta il tuo ledger beancount.io). Non devi avere l'interfaccia Fava aperta o accessibile.
Cosa succede se revoco il mio accesso MCP?
Le sessioni MCP in corso riceveranno errori 401 alla successiva chiamata di strumento. I client che supportano OAuth 2.1 tenteranno automaticamente di ri-autorizzare, chiedendoti di accedere di nuovo.
Sotto il Cofano
Per i curiosi tecnici — come è costruito il server.
Perché MCP invece di costruire una nostra API/plug-in per ogni strumento AI?
MCP è lo standard emergente ed è già supportato da tutti i principali editor AI. Costruire un server MCP conforme ci dà compatibilità con l'intero ecosistema contemporaneamente, invece di mantenere integrazioni separate per Claude, Cursor, Windsurf e qualsiasi altra cosa arriverà il prossimo trimestre. Il protocollo gestisce scoperta, schemi degli strumenti e streaming — noi ci concentriamo sulla logica di dominio.
Perché OAuth 2.1 invece di chiavi API statiche?
OAuth 2.1 con PKCE è ciò che la specifica MCP raccomanda per i server remoti, ed è ciò che client come Claude Code implementano nativamente. Il vantaggio pratico: gli utenti non toccano mai un token. Il client scopre il server di autorizzazione tramite il nostro endpoint di metadati .well-known/oauth-protected-resource, completa PKCE e gestisce l'aggiornamento automaticamente. I token statici rimangono supportati come soluzione di ripiego per i client che non hanno implementato il flusso completo.
Perché HTTP Streamable invece del trasporto SSE o stdio?
HTTP Streamable è il trasporto MCP progettato per server remoti su HTTPS. Stdio è per processi locali. SSE (il trasporto MCP più vecchio) viene deprecato a favore di HTTP Streamable. I nostri utenti si collegano da client AI che non sono co-localizzati con il nostro server, quindi HTTP Streamable è la scelta corretta e lungimirante.
Perché la sessione MCP è stateless (nessun sessionIdGenerator)?
Impostiamo sessionIdGenerator: undefined per rendere ogni richiesta completamente stateless — nessuno stato di sessione lato server viene allocato o conservato tra le chiamate agli strumenti. Questo corrisponde alla modalità stateless della specifica HTTP Streamable e mantiene il server scalabile orizzontalmente senza affinità di sessione. Il contesto dello strumento (identità del ledger, client API Fava) viene ricostruito per ogni richiesta dal token OIDC convalidato.
Come funziona la verifica dell'accesso al ledger?
Dopo la convalida del token OIDC, resolveLedgerAccess verifica tramite l'API Fava che l'utente autenticato abbia effettivamente accesso al ledger richiesto. Questo impedisce che un token valido per un ledger venga usato per sondare il ledger di un altro utente (difesa in profondità oltre al token firmato).
Dove conferma le modifiche editLedgerFiles?
Chiama changeLedgerFiles sull'API Fava, che crea un commit git nel repository Gitea del ledger con il messaggio Modifica AI: <descrizione>. La descrizione proviene dal campo description che l'AI compila — mostrato all'utente nei client MCP ben educati prima dell'esecuzione.
Cos'è l'opzione dry_run su editLedgerFiles?
dry_run: true convalida tutte le operazioni sui file (verifica che i file esistano, controlla che le vecchie stringhe str_replace corrispondano esattamente una volta) e restituisce un'anteprima di ciò che verrebbe confermato — senza scrivere effettivamente su git. Questo è utile per i client AI che vogliono mostrare una differenza all'utente prima di confermare.
Qual è la superficie di errore visibile ai client AI?
Gli errori degli strumenti vengono restituiti come { isError: true, content: [{ type: "text", text: "..." }] } — il formato di errore strutturato dell'SDK MCP. Il client AI riceve il messaggio di errore come testo e può decidere come gestirlo (riprova, segnala all'utente, ecc.). I fallimenti di autenticazione a livello HTTP (401) includono un header WWW-Authenticate che punta ai metadati della risorsa protetta OAuth, in modo che i client conformi possano riavviare automaticamente il flusso di autorizzazione.
