Beancount MCP : connectez votre grand livre à Claude, Cursor et n'importe quel assistant IA

Web Beancount lance son serveur MCP — dialoguez avec votre grand livre depuis Claude, Cursor et n'importe quel outil IA que vous utilisez déjà

Vos données comptables rencontrent votre flux de travail IA. Sans copier-coller. Sans exports. Il suffit de demander.

Aujourd'hui, Web Beancount annonce le serveur Beancount MCP — un point de terminaison Model Context Protocol (MCP) qui vous permet de connecter votre grand livre Beancount directement à Claude Desktop, Claude Code, Cursor, Windsurf ou tout autre client IA compatible MCP. Pour la première fois, les utilisateurs avancés peuvent poser des questions comptables, exécuter des requêtes BQL, et même modifier des fichiers de grand livre depuis les outils IA dans lesquels ils passent déjà leurs journées — sans changer d'onglet ni quitter leur flux de travail.

Les fichiers Beancount en texte brut sont puissants précisément parce que ce ne sont que des fichiers. Mais répondre à « combien ai-je dépensé en voyages le trimestre dernier ? » exige toujours de connaître la syntaxe BQL, de savoir où se trouvent vos fichiers et de copier les résultats dans une conversation. Le serveur Beancount MCP élimine entièrement cette friction.

Une fois le serveur Beancount MCP configuré dans votre client IA, vous pouvez :

Demander « quelle est ma valeur nette aujourd'hui ? » et obtenir une réponse en direct tirée de votre grand livre réel
Demander un récapitulatif des dépenses du mois dernier et laisser l'IA écrire la requête BQL à votre place
Dire à l'IA d'ajouter une transaction et la voir valider la modification dans le dépôt git de votre grand livre
Parcourir et lire vos fichiers .beancount sans jamais quitter votre éditeur

Le serveur est limité à un grand livre : chaque session MCP est autorisée pour exactement un grand livre à l'aide d'OAuth 2.1. Des clients comme Claude Code découvrent et complètent le flux d'autorisation automatiquement — aucune gestion manuelle de jetons n'est nécessaire. Votre grand livre reste là où il se trouve déjà, sur le backend Web Beancount : le client IA envoie des appels d'outils structurés à notre serveur, qui lit ou modifie votre grand livre en votre nom et renvoie les résultats. Le serveur MCP lui-même ne stocke rien de plus que ce que contient la conversation de votre propre client IA.

Le serveur Beancount MCP est disponible dès aujourd'hui pour tous les utilisateurs de Web Beancount.

Pour commencer

Le serveur Beancount MCP est disponible. Ajoutez-le à votre client IA en moins d'une minute.

URL du serveur MCP

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

Claude Code (recommandé — flux OAuth 2.1 complet, aucun jeton requis)

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

Lors de la première utilisation, Claude Code ouvrira une fenêtre de navigateur. C'est dans l'invite du navigateur que vous choisissez le grand livre à connecter — approuvez une fois, et les identifiants se renouvellent automatiquement. Vous avez plusieurs grands livres ? Ajoutez à nouveau le serveur sous un autre nom (claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp) et autorisez l'autre grand livre dans sa propre invite.

Claude Desktop / Cursor / Windsurf / Zed

Ajoutez le serveur à la configuration MCP de votre client (claude_desktop_config.json ou équivalent). Les clients prenant en charge OAuth 2.1 ouvrent la même invite de navigateur lors de la première utilisation — choisissez-y votre grand livre :

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

Si votre client ne prend pas encore en charge le flux OAuth, générez un jeton statique (limité à un seul grand livre) depuis les paramètres de votre compte beancount.io et transmettez-le sous forme d'en-tête :

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Vous n'avez pas de compte Web Beancount ? Inscrivez-vous sur beancount.io — votre grand livre n'est qu'à un git push.

Foire aux questions

FAQ clients

Qu'est-ce que MCP et pourquoi est-ce important pour Beancount ?

MCP (Model Context Protocol) est une norme ouverte qui permet aux assistants IA d'appeler des outils et des sources de données externes de manière structurée et sûre. Voyez-le comme un port USB pour l'IA : au lieu de deviner ou de vous demander de coller des données, l'IA se connecte directement à vos systèmes. Pour les utilisateurs de Beancount, cela signifie que votre client IA peut interroger les données réelles de votre grand livre, lire vos fichiers réels et apporter des modifications précises — au lieu de deviner ce qu'ils pourraient contenir.

Quels clients IA fonctionnent avec le serveur Beancount MCP ?

Tout client compatible MCP prenant en charge OAuth 2.1 fonctionne d'emblée. Le serveur Beancount MCP met en œuvre le flux d'autorisation OAuth 2.1 complet avec PKCE, de sorte que des clients comme Claude Code découvrent automatiquement le point de terminaison d'autorisation du serveur et vous invitent à vous connecter — sans copie manuelle de jeton ni configuration. Une fois que vous avez approuvé l'accès, le client stocke et renouvelle les identifiants automatiquement.

Parmi les clients connus pour prendre en charge MCP + OAuth 2.1 figurent Claude Code CLI, Claude Desktop, Cursor, Windsurf et Zed. À mesure que l'écosystème MCP se développe, tout nouveau client conforme à la spécification MCP OAuth 2.1 fonctionnera sans aucune modification de notre côté.

Comment connecter mon grand livre ?

Pour les clients prenant en charge OAuth 2.1 (comme Claude Code) :

Ajoutez l'URL du serveur Beancount MCP à la configuration MCP de votre client.
Le client ouvre automatiquement une fenêtre de navigateur pour autoriser l'accès.
Connectez-vous avec votre compte Web Beancount et choisissez le grand livre auquel vous souhaitez accorder l'accès.
Terminé — le client se charge du stockage et du renouvellement des jetons à partir de là.

Pour les clients ne prenant pas en charge OAuth 2.1, générez un jeton statique (limité à un seul grand livre) depuis les paramètres de votre compte Web Beancount et transmettez-le sous forme d'en-tête Authorization: Bearer.

Est-ce la même chose que la fonctionnalité de conversation « Ask AI » du tableau de bord ?

Elles partagent les mêmes outils sous-jacents de grand livre (requêtes BQL, lecture/écriture de fichiers), mais le serveur MCP est un point d'entrée différent. La fonctionnalité Ask AI du tableau de bord est une expérience de conversation hébergée avec un bac à sable Claude Code adossé à Cloudflare. Le serveur MCP est un point de terminaison de protocole auquel vous vous connectez depuis le client IA de votre choix — vous offrant plus de contrôle, plus de modèles et une intégration plus poussée à votre flux de travail existant.

Que peut réellement faire l'IA avec mon grand livre ?

Le serveur MCP expose quatre outils :

Outil	Ce qu'il fait
`runBqlQuery`	Exécute BQL (Beancount Query Language) pour interroger les soldes, transactions et comptes
`listLedgerFiles`	Parcourt l'arborescence des répertoires de votre dépôt de grand livre
`readLedgerFiles`	Lit le contenu des fichiers `.beancount` et d'autres documents de grand livre
`editLedgerFiles`	Crée, met à jour, remplace ou supprime des fichiers dans un commit git atomique

L'IA peut les combiner : découvrir la structure de vos fichiers, lire les fichiers pertinents pour le contexte, écrire une requête BQL pour répondre à votre question, ou proposer et valider une modification.

L'IA peut-elle modifier mon grand livre à mon insu ?

Les modifications de fichiers exigent que le client IA appelle editLedgerFiles en décrivant ce qu'il change. Les clients MCP bien conçus (dont Claude Code) vous le présentent avant l'exécution. Les modifications prennent aussi en charge un mode dry_run qui affiche un aperçu des changements exacts sans rien écrire, afin que votre client puisse d'abord vous montrer un diff. Et chaque changement validé est un véritable commit git dans le dépôt de votre grand livre : vous disposez ainsi d'une piste d'audit complète et pouvez tout annuler avec les outils git standard.

Mes données sont-elles envoyées à un tiers ?

Les données de votre grand livre transitent par le backend Web Beancount (qui gère déjà votre grand livre) et sont renvoyées à votre client IA sous forme de résultats structurés. Le modèle d'IA que vous utilisez (par exemple, Claude) reçoit les résultats des outils comme n'importe quel autre contexte. Le serveur MCP ne stocke aucune donnée au-delà de ce que contient déjà la conversation de votre client IA.

Chaque jeton est limité à un grand livre — qu'est-ce que cela signifie ?

Lorsque vous autorisez le serveur MCP, vous choisissez le grand livre auquel accorder l'accès. Cette session ne peut accéder qu'à ce grand livre. Si vous avez plusieurs grands livres, vous autorisez des sessions distinctes. Cela limite le rayon d'impact : une session pour votre grand livre personnel ne peut pas toucher votre grand livre professionnel.

Le serveur MCP nécessite-t-il que l'interface web Fava soit en cours d'exécution ?

Non. Le serveur MCP communique avec l'API Fava interne gérée par l'infrastructure de Web Beancount (Fava est l'interface web qui alimente votre grand livre beancount.io). Vous n'avez pas besoin d'avoir l'interface Fava ouverte ou accessible.

Que se passe-t-il si je révoque mon accès MCP ?

Les sessions MCP en cours recevront des erreurs 401 lors du prochain appel d'outil. Les clients prenant en charge OAuth 2.1 tenteront automatiquement de se réautoriser, en vous invitant à vous reconnecter.

Sous le capot

Pour les curieux de technique — comment le serveur est construit.

Pourquoi MCP plutôt que de construire notre propre API/plugin pour chaque outil IA ?

MCP est la norme émergente, déjà prise en charge par tous les grands éditeurs IA. Construire un seul serveur MCP conforme nous donne d'un coup la compatibilité avec tout l'écosystème, au lieu de maintenir des intégrations distinctes pour Claude, Cursor, Windsurf et tout ce qui sortira le trimestre prochain. Le protocole gère la découverte, les schémas d'outils et le streaming — nous nous concentrons sur la logique métier.

Pourquoi OAuth 2.1 plutôt que des clés d'API statiques ?

OAuth 2.1 avec PKCE est ce que recommande la spécification MCP pour les serveurs distants, et c'est ce que des clients comme Claude Code implémentent nativement. L'avantage pratique : les utilisateurs ne touchent jamais à un jeton. Le client découvre le serveur d'autorisation via notre point de terminaison de métadonnées .well-known/oauth-protected-resource, complète PKCE et gère le renouvellement automatiquement. Les jetons statiques restent pris en charge comme solution de repli pour les clients qui n'ont pas implémenté le flux complet.

Pourquoi Streamable HTTP plutôt que le transport SSE ou stdio ?

Streamable HTTP est le transport MCP conçu pour les serveurs distants sur HTTPS. Stdio est destiné aux processus locaux. SSE (l'ancien transport MCP) est en cours d'abandon au profit de Streamable HTTP. Nos utilisateurs se connectent depuis des clients IA qui ne sont pas co-localisés avec notre serveur, ce qui fait de Streamable HTTP le choix approprié et tourné vers l'avenir.

Pourquoi la session MCP est-elle sans état (pas de sessionIdGenerator) ?

Nous définissons sessionIdGenerator: undefined pour rendre chaque requête totalement sans état — aucun état de session côté serveur n'est alloué ni conservé entre les appels d'outils. Cela correspond au mode sans état de la spécification Streamable HTTP et maintient le serveur scalable horizontalement, sans affinité de session. Le contexte de l'outil (identité du grand livre, client de l'API Fava) est reconstruit à chaque requête à partir du jeton OIDC validé.

Comment fonctionne la vérification de l'accès au grand livre ?

Après validation du jeton OIDC, resolveLedgerAccess vérifie via l'API Fava que l'utilisateur authentifié a effectivement accès au grand livre demandé. Cela empêche qu'un jeton valide pour un grand livre soit utilisé pour sonder le grand livre d'un autre utilisateur (défense en profondeur par-dessus le jeton signé).

Où editLedgerFiles effectue-t-il ses commits ?

Il appelle changeLedgerFiles sur l'API Fava, qui crée un commit git dans le dépôt Gitea du grand livre avec le message AI edit: <description>. La description provient du champ description que l'IA remplit — présentée à l'utilisateur dans les clients MCP bien conçus avant l'exécution.

Qu'est-ce que l'option dry_run de editLedgerFiles ?

dry_run: true valide toutes les opérations sur les fichiers (vérifie que les fichiers existent, que les anciennes chaînes de str_replace correspondent exactement une fois) et renvoie un aperçu de ce qui serait validé — sans réellement écrire dans git. C'est utile pour les clients IA qui veulent montrer un diff à l'utilisateur avant de valider.

Quelle est la surface d'erreur visible par les clients IA ?

Les erreurs d'outil sont renvoyées sous la forme { isError: true, content: [{ type: "text", text: "..." }] } — le format d'erreur structuré du SDK MCP. Le client IA reçoit le message d'erreur sous forme de texte et peut décider comment le gérer (réessayer, signaler à l'utilisateur, etc.). Les échecs d'authentification au niveau HTTP (401) incluent un en-tête WWW-Authenticate pointant vers les métadonnées de la ressource protégée OAuth, de sorte que les clients conformes peuvent automatiquement relancer le flux d'autorisation.