Installer
Cette page vous mène de zéro à avenir-mcp qui fonctionne, en une dizaine de minutes. Chaque étape se termine par une vérification : vous savez qu’elle a marché avant de passer à la suivante.
- Installer uv, l’outil qui lance avenir-mcp.
- Obtenir un jeton YNAB, l’accès d’avenir-mcp à vos plans.
- Premier lancement à la main, une seule fois.
- Ajouter avenir-mcp à votre client.
- Vérifier que tout fonctionne avec une première question.
- Autoriser les modifications, si vous voulez que l’agent range pour vous.
Ce qu’il vous faut
Section intitulée « Ce qu’il vous faut »| Pourquoi | Où l’obtenir | |
|---|---|---|
| Un compte YNAB | avenir-mcp lit et modifie vos plans | app.ynab.com |
| Un client MCP | l’application avec laquelle vous parlez ; c’est elle qui lance avenir-mcp | Claude Code, Claude Desktop, Cursor, VS Code… |
| uv | télécharge et lance avenir-mcp, et le Python dont il a besoin, dans un environnement isolé | l’étape suivante |
Vous n’avez pas besoin d’installer Python, de cloner le dépôt ni de créer un environnement virtuel : uv s’en charge.
Installer uv
Section intitulée « Installer uv »Dans un terminal :
curl -LsSf https://astral.sh/uv/install.sh | shOu, avec Homebrew : brew install uv.
Dans PowerShell :
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Ou, avec WinGet : winget install --id=astral-sh.uv -e.
Fermez et rouvrez le terminal, puis vérifiez :
uv --versionUne version s’affiche, par exemple uv 0.12.19. Commande introuvable ? L’installeur
ajoute uv au PATH des nouveaux terminaux seulement : ouvrez-en un nouveau. Détails dans
la documentation d’uv.
Obtenir un jeton YNAB
Section intitulée « Obtenir un jeton YNAB »- Connectez-vous à YNAB dans un navigateur, sur app.ynab.com — les applications mobiles n’affichent pas les réglages développeur.
- Cliquez sur votre nom en haut à gauche, puis Account Settings.
- Ouvrez Developer Settings.
- Sous Personal Access Tokens, cliquez sur New Token, saisissez votre mot de passe YNAB, puis Generate.
- Copiez le jeton affiché en haut de la page : une longue suite de lettres, de chiffres et de tirets. YNAB ne l’affiche qu’une fois. Si vous le perdez, créez-en un autre et révoquez l’ancien.
Installer l’extension Claude Desktop
Section intitulée « Installer l’extension Claude Desktop »Un seul fichier installe avenir-mcp, le Python sur lequel il tourne et les réglages dont il a besoin. Cette section ne comporte ni terminal ni fichier de configuration, et aucune de ses étapes ne diffère entre Windows, macOS et Linux, sauf là où elle le dit.
Télécharger pour Claude DesktopLe fichier correspond toujours à la dernière version disponible ; la version qu’il installe est indiquée dans le fichier lui-même, et les étapes ci-dessous sont les mêmes quelle que soit cette version.
-
Installez Claude Desktop, si ce n’est pas déjà fait, depuis claude.ai/download, et lancez-le une fois.
-
Téléchargez l’extension à l’aide du bouton ci-dessus ou via ce lien. Elle pèse environ 17 ko et sera enregistrée dans votre dossier de téléchargements sous le nom
avenir-mcp.mcpb.Sous Windows, Edge ou Chrome peuvent vous avertir que le fichier n’est pas couramment téléchargé. Cet avertissement porte sur la rareté du fichier, non sur son contenu : cliquez sur les trois points à côté du téléchargement, puis sur Keep. Ce que vous pouvez vérifier du fichier à la place est écrit dans SECURITY.md.
-
Faites glisser le fichier vers Settings → Extensions. Ouvrez Claude Desktop, puis Settings → Extensions : cet écran répertorie les extensions dont vous disposez, et c’est là que le fichier s’installe. Sélectionnez le fichier
avenir-mcp.mcpbdans votre dossier de téléchargements ou dans la liste des téléchargements de votre navigateur, puis faites-le glisser sur cet écran. La boîte de dialogue d’installation s’ouvre.Un double-clic sur le fichier peut également fonctionner, si votre système ouvre déjà les fichiers
.mcpbavec Claude Desktop. Si, au contraire, Windows vous demande avec quelle application ouvrir le fichier, fermez cette fenêtre : les fichiers.mcpbne sont associés à aucune application, et la recherche declaude.exene donne aucun résultat. Faites plutôt glisser le fichier sur l’écran Extensions.Aucune des deux ne fonctionne ? Sur ce même écran, ouvrez les Advanced settings puis, sous Extension Developer, cliquez sur Install Extension… ; sélectionnez le fichier dans votre dossier de téléchargements.
-
Installez-la. La boîte de dialogue donne le nom de l’extension, avenir-mcp for YNAB, et dit ce qu’elle fait. Cliquez sur Install.
-
Collez votre jeton dans le champ nommé YNAB personal access token, celui de l’étape précédente.
Ctrl+Vsous Windows et Linux,⌘+Vsur macOS. Le champ masque ce que vous y collez ; Claude Desktop le garde là où votre système conserve les mots de passe, et il n’est écrit dans aucun fichier que vous pourriez ouvrir. -
Laissez la case Allow changes to your plans décochée, puis enregistrez. avenir-mcp répond aux questions et ne modifie rien tant que cette case reste décochée. Vous pourrez la cocher plus tard, au même endroit.
-
Vérifiez qu’elle est bien là. Settings → Extensions affiche désormais avenir-mcp for YNAB, activée.
-
Posez-lui une question. Dans une nouvelle conversation, écrivez : « Liste mes plans YNAB. » Claude vous demande d’autoriser l’outil la première fois ; autorisez-le, et la réponse donne les noms de vos plans. La toute première réponse prend quelques secondes de plus que les suivantes, le temps que Claude Desktop récupère Python et avenir-mcp.
L’installation est terminée. La suite de cette page traite des autres clients et de l’installation à la main ; continuez avec votre première conversation, ou avec autoriser les modifications si vous voulez que l’agent range pour vous.
| Pour | Faire |
|---|---|
| Changer le jeton, ou autoriser les modifications | Settings → Extensions → avenir-mcp for YNAB |
| Mettre à jour | téléchargez à nouveau l’extension et faites-la glisser sur l’écran Settings → Extensions, par-dessus celle qui est déjà installée ; le lien renvoie toujours vers la dernière version disponible |
| Retirer | retirez-la depuis Settings → Extensions ; le jeton part avec elle |
Premier lancement à la main
Section intitulée « Premier lancement à la main »Avant de configurer un client, lancez avenir-mcp une fois à la main. Cela le télécharge et prouve qu’il démarre.
YNAB_API_KEY=votre-jeton uvx avenir-mcp$env:YNAB_API_KEY = "votre-jeton"; uvx avenir-mcpLe premier lancement télécharge avenir-mcp et Python : de quelques secondes à une minute. Ensuite rien ne s’affiche et la commande ne rend pas la main — c’est normal : avenir-mcp attend qu’un client lui parle. Appuyez sur Ctrl+C pour l’arrêter.
Une erreur s’affiche à la place ? Voir le dépannage.
Ajouter avenir-mcp à votre client
Section intitulée « Ajouter avenir-mcp à votre client »Choisissez votre client. Ces configurations sont en lecture seule : avenir-mcp répond aux questions mais ne modifie rien. Autoriser les modifications vient après. Cursor, LM Studio et VS Code permettent de l’installer en un seul clic, à partir du bouton situé en haut de leur onglet.
Dans un terminal :
claude mcp add avenir-mcp --scope user \ --env YNAB_API_KEY=votre-jeton \ -- uvx avenir-mcp| Élément | Sens |
|---|---|
claude mcp add avenir-mcp |
enregistre un serveur MCP nommé avenir-mcp |
--scope user |
pour tous vos projets ; sans lui, seulement pour le dossier courant |
--env YNAB_API_KEY=… |
l’environnement avec lequel avenir-mcp démarre |
-- |
ce qui suit est la commande qui lance le serveur |
uvx avenir-mcp |
cette commande |
Claude Code garde cela, jeton compris, dans ~/.claude.json, lisible par vous seul.
L’extension est la voie courte, et celle qui ne demande pas de terminal : Installer l’extension Claude Desktop.
Ou à la main, si vous préférez écrire la configuration vous-même :
- Ouvrez Claude Desktop, puis Settings → Developer → Edit Config. Cela ouvre
claude_desktop_config.json:- macOS :
~/Library/Application Support/Claude/claude_desktop_config.json - Windows :
%APPDATA%\Claude\claude_desktop_config.json
- macOS :
- Si le fichier est vide, collez tout ceci. S’il liste déjà des serveurs, ajoutez
seulement le bloc
"avenir-mcp": { … }dans lemcpServersexistant, avec une virgule après l’entrée précédente.{"mcpServers": {"avenir-mcp": {"command": "uvx","args": ["avenir-mcp"],"env": { "YNAB_API_KEY": "votre-jeton" }}}} - Enregistrez, puis quittez complètement Claude Desktop — ⌘Q sur macOS, ou depuis l’icône de la barre des tâches sous Windows — et rouvrez-le.
- Cliquez sur le bouton : Cursor vous demande de confirmer, puis ajoute
avenir-mcpà sa liste de serveurs. - Ouvrez Cursor Settings → MCP, remplacez
votre-jetonpar le jeton que vous avez copié, et vérifiez queavenir-mcpest activé.
Ou à la main : créez ou ouvrez ~/.cursor/mcp.json (tous les projets) ou
.cursor/mcp.json dans un projet, et ajoutez :
{ "mcpServers": { "avenir-mcp": { "command": "uvx", "args": ["avenir-mcp"], "env": { "YNAB_API_KEY": "votre-jeton" } } }}- Cliquez sur le bouton : VS Code vous demande de confirmer, puis vous invite à saisir votre jeton dans un champ de mot de passe et le conserve dans son propre espace de stockage sécurisé.
- Utilisez-le dans Copilot Chat en mode Agent.
Ou à la main : créez .vscode/mcp.json dans votre espace de travail. VS Code demande
également le jeton à cet endroit ; le fichier ne le contient donc jamais : un fichier
d’un espace de travail peut facilement être ajouté par erreur à un dépôt.
{ "inputs": [ { "type": "promptString", "id": "ynab-token", "description": "Jeton d'accès personnel YNAB", "password": true } ], "servers": { "avenir-mcp": { "type": "stdio", "command": "uvx", "args": ["avenir-mcp"], "env": { "YNAB_API_KEY": "${input:ynab-token}" } } }}Exécutez ensuite la commande MCP: List Servers, choisissez avenir-mcp, puis
Start Server.
- Ouvrez
~/.gemini/settings.json(créez-le si besoin) et ajoutez :{"mcpServers": {"avenir-mcp": {"command": "uvx","args": ["avenir-mcp"],"env": { "YNAB_API_KEY": "votre-jeton" }}}} - Lancez
geminiet tapez/mcp:avenir-mcpapparaît avec ses outils. Le modèle est celui qu’utilise Gemini CLI.
- Ouvrez
~/.codex/config.toml(créez-le si besoin) et ajoutez :[mcp_servers.avenir]command = "uvx"args = ["avenir-mcp"]env = { YNAB_API_KEY = "votre-jeton" } - Lancez
codexet tapez/mcp:avenir-mcpapparaît avec ses outils. Le modèle est celui qu’utilise Codex.
Pour un modèle qui tourne sur votre propre machine — voir Choisir un modèle.
- Cliquez sur le bouton : LM Studio vous demande de confirmer, puis ajoute
avenir-mcpà son fichiermcp.json. - Dans LM Studio, ouvrez l’onglet Program de la barre latérale droite, puis Install → Edit mcp.json, et remplacez
votre-jetonpar le jeton que vous avez copié. - Enregistrez, chargez un modèle qui gère l’appel d’outils, et ouvrez une conversation : LM Studio demande avant chaque appel d’outil.
Ou manuellement : ajoutez ceci dans le même fichier mcp.json :
{ "mcpServers": { "avenir-mcp": { "command": "uvx", "args": ["avenir-mcp"], "env": { "YNAB_API_KEY": "votre-jeton" } } }}Tout client MCP qui lance ses serveurs en stdio fonctionne. Indiquez-lui :
| Réglage | Valeur |
|---|---|
| commande | uvx |
| arguments | avenir-mcp |
| environnement | YNAB_API_KEY = votre jeton |
Pour l’exécuter dans un conteneur, créez l’image à partir du fichier Dockerfile situé
à la racine du dépôt à l’aide de la commande docker build -t avenir-mcp ., puis
indiquez au client docker comme commande et run -i --rm -e YNAB_API_KEY avenir-mcp
comme arguments, afin que le jeton soit transmis via l’environnement plutôt que par la
ligne de commande.
Pour les clients qui se connectent à une URL, voir Lancer en HTTP.
Vérifier que tout fonctionne
Section intitulée « Vérifier que tout fonctionne »claude mcp listavenir-mcp doit être connecté :
avenir-mcp: uvx avenir-mcp - ✔ ConnectedLancez ensuite claude et tapez /mcp : avenir-mcp affiche ses 19 outils.
Ouvrez la liste des serveurs MCP ou des outils du client : avenir-mcp doit être actif,
avec 19 outils.
Demandez maintenant, dans une nouvelle conversation : « Liste mes plans YNAB. »
L’agent appelle list_plans — votre
client peut vous demander l’autorisation — et répond avec leurs noms. Ici, le plan de
démonstration utilisé dans toute cette documentation :
[ { "id": "demo-budget", "name": "Foyer de démonstration", "first_month": "2026-06-01", "last_month": "2026-09-01" }]avenir-mcp fonctionne. Continuez avec votre première conversation, ou autorisez d’abord les modifications.
Autoriser les modifications
Section intitulée « Autoriser les modifications »Pour que l’agent puisse classer des transactions, déplacer de l’argent entre catégories
ou rapprocher des comptes, ajoutez AVENIR_MCP_WRITE=1 à l’environnement d’avenir-mcp.
Installée depuis l’extension : ouvrez Settings → Extensions → avenir-mcp for YNAB, cochez Allow changes to your plans, enregistrez, et redémarrez Claude Desktop. L’extension pose la variable pour vous, il n’y a rien à taper.
Retirez avenir-mcp et ajoutez-le à nouveau avec la variable en plus :
claude mcp remove avenir-mcp --scope userclaude mcp add avenir-mcp --scope user \ --env YNAB_API_KEY=votre-jeton \ --env AVENIR_MCP_WRITE=1 \ -- uvx avenir-mcpAjoutez la variable à côté du jeton, enregistrez, puis redémarrez le client :
"env": { "YNAB_API_KEY": "votre-jeton", "AVENIR_MCP_WRITE": "1" }Ajoutez la variable à côté du jeton dans ~/.codex/config.toml, puis relancez Codex :
env = { YNAB_API_KEY = "votre-jeton", AVENIR_MCP_WRITE = "1" }La valeur doit être exactement 1. Vérification : le client liste maintenant 32
outils au lieu de 19.
| Lecture seule (défaut) | Avec AVENIR_MCP_WRITE=1 |
|
|---|---|---|
| Outils listés | 19 | 32 |
| Classer, budgéter, rapprocher, créer | — | prévisualisé, confirmé par vous, annulable |
| Si l’agent comprend mal | rien ne peut changer | un changement que vous avez confirmé, et que vous pouvez annuler |
Chaque changement vous est montré avant d’être appliqué : voir Sécurité par conception.
Mettre à jour, retirer, révoquer
Section intitulée « Mettre à jour, retirer, révoquer »| Pour | Faire |
|---|---|
| Mettre à jour | uvx récupère les nouvelles versions de lui-même de temps en temps ; forcez-le avec uvx --refresh avenir-mcp. Pour mettre à jour l’extension Claude Desktop, il suffit de la télécharger à nouveau et de la glisser-déposer sur l’écran Settings → Extensions, par-dessus celle qui est déjà installée |
| Retirer | claude mcp remove avenir-mcp --scope user, ou supprimez l’entrée avenir-mcp de la configuration du client. L’extension se retire depuis Settings → Extensions, jeton compris |
| Nettoyer | le seul fichier d’avenir-mcp sur votre machine est son journal, dans ~/.local/state/avenir-mcp/ |
| Révoquer le jeton | YNAB → Account Settings → Developer Settings → Revoke à côté du jeton |
Et ensuite
Section intitulée « Et ensuite »- Votre première conversation : une visite guidée.
- Fonctionnalités : tout ce qu’avenir-mcp sait faire.
- Configuration : chaque variable d’environnement.
Projet non officiel. « We are not affiliated, associated, or in any way officially connected with YNAB or any of its subsidiaries or affiliates. The official YNAB website can be found at https://www.ynab.com. The names YNAB and You Need A Budget, as well as related names, tradenames, marks, trademarks, emblems, and images are registered trademarks of YNAB. » Nous ne sommes ni affiliés, ni associés, ni liés officiellement de quelque manière que ce soit à YNAB ou à ses filiales et sociétés affiliées. Le site officiel de YNAB se trouve à l’adresse https://www.ynab.com. Les noms YNAB et You Need A Budget, ainsi que les noms, dénominations commerciales, marques, emblèmes et images qui s’y rattachent, sont des marques déposées de YNAB. avenir-mcp est fourni tel quel, sans garantie, et n’est pas un conseil financier. Mentions légales · Confidentialité