Demandez à votre assistant IA combien vous avez dépensé le mois dernier, quels comptes nécessitent un rapprochement, ou où classer une transaction. Beancount MCP lui donne accès aux requêtes, comptes et fichiers sources de votre grand livre hébergé, afin qu'il puisse travailler à partir de vos livres et montrer les preuves derrière sa réponse.
Avec l'autorisation d'écriture, l'assistant peut également ajouter des transactions et mettre à jour les fichiers du grand livre. Vous pouvez lui demander de prévisualiser les modifications prises en charge, d'examiner les écritures proposées et de vérifier le grand livre après une modification.
MCP signifie Model Context Protocol : un standard pour connecter des applications d'IA à des outils et données externes. Cette connexion fonctionne avec les grands livres hébergés sur Beancount.io. Les réponses de votre assistant reflètent les transactions et prix enregistrés là-bas ; connecter MCP ne rend pas automatiquement ces enregistrements à jour.
Connectez votre client IA
Utilisez un client qui prend en charge MCP distant sur Streamable HTTP. L'URL du serveur est :
https://beancount.io/api-gateway/mcpClaude Code
Ajoutez le serveur depuis votre terminal :
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpOuvrez Claude Code, exécutez /mcp, sélectionnez beancount et suivez son flux d'authentification. Connectez-vous à Beancount.io et examinez les autorisations demandées. Revenez à /mcp pour confirmer la connexion. Consultez les instructions MCP de Claude Code pour les détails spécifiques au client.
La page de consentement vous permet de restreindre l'accès à un seul grand livre ou de choisir explicitement Tous les grands livres accessibles. Une restriction à un seul grand livre est un point de départ utile. Avec un accès plus large, indiquez à l'assistant quel grand livre utiliser, comme alice/personal ; les outils de grand livre doivent identifier leur cible à chaque appel.
Claude Desktop et Claude sur le web
Ouvrez Personnaliser → Connecteurs, choisissez Ajouter un connecteur personnalisé, saisissez l'URL du serveur et connectez votre compte Beancount.io. Activez le connecteur pour la conversation où vous souhaitez l'utiliser. Les comptes d'organisation peuvent nécessiter qu'un propriétaire ajoute le connecteur d'abord. Suivez le guide des connecteurs distants de Claude.
Cursor
Ajoutez le serveur à votre ~/.cursor/mcp.json personnel :
{
"mcpServers": {
"beancount": {
"url": "https://beancount.io/api-gateway/mcp"
}
}
}Terminez la connexion OAuth lorsque Cursor le demande, puis vérifiez que les outils du serveur sont disponibles. La documentation MCP de Cursor couvre la configuration et les paramètres d'approbation des outils.
Clés API personnelles
Pour un client qui accepte les identifiants bearer, vous pouvez créer une clé API personnelle dans Paramètres → Jetons d'accès personnels. La création d'une clé nécessite un plan Beancount.io payant. Sélectionnez ledger.read pour les requêtes, restreignez éventuellement la clé à un seul grand livre et copiez-la lorsqu'elle est affichée. Configurez l'en-tête d'autorisation de votre client comme Authorization: Bearer VOTRE_CLÉ en utilisant ses paramètres d'identifiants privés.
Gardez la clé hors de la configuration partagée du projet. Les clients OAuth gèrent les identifiants via leur flux de connexion ; vous n'avez pas besoin de créer une clé personnelle pour ce chemin.
Commencez par une question sur les dépenses
Essayez ceci après la connexion, en remplaçant le nom du grand livre par le vôtre :
Utilisez
alice/personal. Identifiez ses comptes et devises, puis résumez les dépenses d'août 2026 par compte. Montrez la plage de dates et le BQL derrière chaque total, gardez les devises séparées et signalez toute erreur de validation du grand livre. Ne modifiez rien.
L'assistant peut découvrir vos grands livres avec listLedgers, apprendre vos noms de comptes via getLedgerContext et exécuter runBqlQueryStructured pour des résultats de requête typés. checkLedger renvoie les erreurs de validation, les nombres d'écritures et le dernier commit.
Une réponse utile inclut le grand livre, la période, les devises, les totaux et les requêtes de support. Pour une question sur la valeur nette, demandez également la méthode d'évaluation et les dates des prix utilisés. Des transactions manquantes ou des prix obsolètes peuvent changer la réponse même lorsque le grand livre passe la validation.
Ajoutez une transaction avec un aperçu
Pour les nouvelles écritures, appendLedgerText accepte du texte Beancount ordinaire et achemine les directives vers des fichiers en utilisant la configuration de votre grand livre. Son option dry_run renvoie un diff et des erreurs de validation projetées avant de valider.
Par exemple :
Préparez un achat de café de 4,50 USD daté du 15 septembre 2026, payé depuis
Assets:Cashet classé sousExpenses:Food. Vérifiez que ces comptes existent et cherchez d'abord une transaction correspondante. UtilisezappendLedgerTextavecdry_run: true, montrez l'écriture proposée et le diff de fichier, et attendez ma confirmation.
Avec ces comptes déjà ouverts, l'écriture proposée ressemblerait à ceci :
2026-09-15 * "Cafe" "Coffee"
Expenses:Food 4.50 USD
Assets:Cash -4.50 USDUtilisez les noms de comptes de votre propre grand livre, puis terminez la révision :
- Vérifiez la date, le montant, les comptes et le fichier de destination dans l'aperçu.
- Confirmez la modification exacte que vous souhaitez que l'assistant applique.
- Demandez-lui d'exécuter
checkLedgeret de signaler le commit résultant et toute erreur.
appendLedgerText rejette les nouvelles erreurs de validation par défaut. Les modifications générales de fichiers utilisent editLedgerFiles, qui peut créer, remplacer, mettre à jour ou supprimer des fichiers en un seul commit Git. Son aperçu signale également un diff et des erreurs projetées. Vérifiez le résultat et exécutez checkLedger après l'écriture : un commit réussi peut encore contenir des erreurs comptables.
Utilisez un flux de travail pour la comptabilité récurrente
Le serveur fournit également des invites MCP réutilisables. Les clients prenant en charge les invites les exposent dans leur sélecteur de commandes ou d'invites :
| Flux de travail | Ce qu'il vous aide à faire |
|---|---|
spending-report | Répondre à une question sur les dépenses avec un BQL de support et aucune écriture de grand livre. |
reconcile-account | Comparer un compte avec un relevé fourni, classer les différences et proposer des écritures manquantes. |
close-month | Examiner les comptes actifs, les assertions de solde, les transactions récurrentes et les indicateurs non résolus. |
categorize-imports | Examiner les transactions bancaires en attente et proposer des catégories en utilisant les comptes existants. |
Ces invites guident l'assistant à travers une procédure. Elles n'exécutent pas un travail comptable simplement parce que vous les sélectionnez et n'accordent pas d'autorisations supplémentaires.
Le rapprochement nécessite un relevé et un solde de clôture. Un résultat de validation propre seul ne peut pas établir que chaque transaction a été enregistrée. Demandez à l'assistant d'identifier tout ce qu'il n'a pas pu vérifier et laissez ces questions visibles dans le rapport.
Pour les importations bancaires, liez d'abord la banque dans Beancount.io. La lecture des détails de connexion nécessite un accès administratif ; la soumission de transactions en attente nécessite une autorisation d'écriture et l'accès approprié à cette connexion bancaire. Examinez les catégories et doublons proposés avant d'autoriser la soumission.
Comprenez l'accès et le traitement des données
Les autorisations de la connexion déterminent ce que l'assistant peut faire :
| Autorisation | Accès |
|---|---|
ledger.read | Interroger et lire les données du grand livre. |
ledger.write | Lire les données et effectuer des modifications ordinaires du grand livre. |
ledger.admin | Lire, écrire et effectuer des opérations administratives là où c'est autorisé. |
Votre accès existant à chaque grand livre s'applique toujours. Restreindre un identifiant à un seul grand livre empêche les appels de grand livre de cibler un autre ; un identifiant non restreint peut sélectionner parmi les grands livres auxquels vous avez accès. Le client OAuth choisit les autorisations à demander, alors lisez l'écran de consentement avant d'approuver.
Le serveur MCP n'affiche pas de boîte de dialogue d'approbation humaine. Les paramètres de votre client déterminent quand il demande avant d'appeler un outil, et les aperçus doivent être demandés explicitement. Les flux de travail d'écriture fournis instruisent l'assistant d'attendre une confirmation. Un identifiant restreint à ledger.read fournit une limite appliquée lorsque vous voulez une analyse sans écritures.
Les résultats d'outils, y compris les transactions interrogées et les fichiers lus par l'assistant, entrent dans le contexte de votre client IA et peuvent être traités par son fournisseur de modèle. Beancount.io conserve votre grand livre, votre historique Git et vos enregistrements opérationnels. Une connexion MCP sans état n'est pas une promesse qu'aucune donnée n'est conservée ; les politiques de données de votre client et de son fournisseur s'appliquent également.
Les clés API personnelles révoquées sont rejetées lors des demandes ultérieures. Les jetons d'accès OAuth durent normalement une heure ; la révocation d'un jeton d'actualisation n'invalide pas immédiatement un jeton d'accès déjà émis. L'accès au grand livre est revérifié lorsque des opérations protégées s'exécutent.
Questions courantes
Cela ouvre-t-il le grand livre sur mon ordinateur portable ?
Le point de terminaison hébergé fonctionne sur votre grand livre Beancount.io. Il n'ouvre pas un fichier .bean local et vous n'avez pas besoin d'un onglet de navigateur Fava ouvert.
En quoi est-ce différent de l'assistant IA du tableau de bord ?
Le tableau de bord fournit sa propre interface de chat. MCP rend les capacités du grand livre disponibles depuis un client IA externe, avec la conversation, le modèle et les paramètres d'approbation de ce client.
Pourquoi puis-je voir un outil mais pas l'utiliser ?
Le catalogue d'outils inclut des opérations que votre identifiant peut ne pas permettre. Vérifiez l'erreur et les autorisations accordées. Un identifiant non restreint a également besoin d'une cible de grand livre explicite pour les outils de grand livre.
Connectez votre grand livre et commencez par une question que vous pouvez vérifier par rapport à vos livres. Gardez la requête avec la réponse, puis ajoutez des autorisations d'écriture lorsque vous voulez de l'aide pour maintenir le grand livre lui-même.
