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.

1. Installer uv, l’outil qui lance avenir-mcp.
2. Obtenir un jeton YNAB, l’accès d’avenir-mcp à vos budgets.
3. Premier lancement à la main, une seule fois.
4. Ajouter avenir-mcp à votre client.
5. Vérifier que tout fonctionne avec une première question.
6. Autoriser les modifications, si vous voulez que l’agent range pour vous.

Ce qu’il vous faut

	Pourquoi	Où l’obtenir
Un compte YNAB	avenir-mcp lit et modifie vos budgets	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

macOS / Linux

Dans un terminal :

curl -LsSf https://astral.sh/uv/install.sh | sh

Ou, avec Homebrew : brew install uv.

Windows

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 --version

Une 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

1. Connectez-vous à YNAB dans un navigateur, sur app.ynab.com — les applications mobiles n’affichent pas les réglages développeur.
2. Cliquez sur votre nom en haut à gauche, puis Account Settings.
3. Ouvrez Developer Settings.
4. Sous Personal Access Tokens, cliquez sur New Token, saisissez votre mot de passe YNAB, puis Generate.
5. 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.

Traitez le jeton comme un mot de passe

Un jeton d’accès personnel peut lire et modifier tous les budgets de votre compte ; YNAB ne propose pas de jeton en lecture seule. Ne le collez jamais dans une conversation avec une IA, un fichier partagé, une issue ou un dépôt. avenir-mcp ne le journalise jamais et ne le renvoie jamais dans une réponse.

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.

macOS / Linux

YNAB_API_KEY=votre-jeton uvx avenir-mcp

Windows

$env:YNAB_API_KEY = "votre-jeton"; uvx avenir-mcp

Le 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

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.

Claude Code

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.

Claude Desktop

1. 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
2. Si le fichier est vide, collez tout ceci. S’il liste déjà des serveurs, ajoutez seulement le bloc "avenir-mcp": { … } dans le mcpServers existant, 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" }
       }
     }
   }

3. 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.

Cursor

1. 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" }
       }
     }
   }

2. Ouvrez Cursor Settings → MCP et vérifiez que avenir-mcp est activé.

VS Code

1. Créez .vscode/mcp.json dans votre espace de travail :

   {
     "servers": {
       "avenir-mcp": {
         "type": "stdio",
         "command": "uvx",
         "args": ["avenir-mcp"],
         "env": { "YNAB_API_KEY": "votre-jeton" }
       }
     }
   }

2. Lancez la commande MCP: List Servers, choisissez avenir-mcp, puis Start Server.
3. Utilisez-le dans Copilot Chat en mode Agent.

Gemini CLI

1. 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" }
       }
     }
   }

2. Lancez gemini et tapez /mcp : avenir-mcp apparaît avec ses outils. Le modèle est celui qu’utilise Gemini CLI.

Codex CLI

1. 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" }

2. Lancez codex et tapez /mcp : avenir-mcp apparaît avec ses outils. Le modèle est celui qu’utilise Codex.

LM Studio

Pour un modèle qui tourne sur votre propre machine — voir Choisir un modèle.

1. Dans LM Studio, ouvrez l’onglet Program de la barre latérale droite, puis Install → Edit mcp.json, et ajoutez :

   {
     "mcpServers": {
       "avenir-mcp": {
         "command": "uvx",
         "args": ["avenir-mcp"],
         "env": { "YNAB_API_KEY": "votre-jeton" }
       }
     }
   }

2. Enregistrez, chargez un modèle qui gère l’appel d’outils, et ouvrez une conversation : LM Studio demande avant chaque appel d’outil.

Autres clients

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 les clients qui se connectent à une URL, voir Lancer en HTTP.

« uvx introuvable » dans une application de bureau

Les applications graphiques ne voient pas toujours le PATH de votre terminal. Si le client ne trouve pas uvx, remplacez "uvx" par son chemin complet, donné par which uvx (macOS, Linux) ou where uvx (Windows) — par exemple "/Users/<vous>/.local/bin/uvx".

Vérifier que tout fonctionne

Claude Code

claude mcp list

avenir-mcp doit être connecté :

avenir-mcp: uvx avenir-mcp - ✔ Connected

Lancez ensuite claude et tapez /mcp : avenir-mcp affiche ses 9 outils.

Autres clients

Ouvrez la liste des serveurs MCP ou des outils du client : avenir-mcp doit être actif, avec 9 outils.

Demandez maintenant, dans une nouvelle conversation : « Liste mes budgets YNAB. » L’agent appelle list_plans — votre client peut vous demander l’autorisation — et répond avec leurs noms. Ici, le budget de démonstration utilisé dans toute cette documentation :

list_plans

[
  {
    "id": "demo-budget",
    "name": "Demo household",
    "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

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.

Claude Code

Retirez avenir-mcp et ajoutez-le à nouveau avec la variable en plus :

claude mcp remove avenir-mcp --scope user
claude mcp add avenir-mcp --scope user \
  --env YNAB_API_KEY=votre-jeton \
  --env AVENIR_MCP_WRITE=1 \
  -- uvx avenir-mcp

Configurations JSON

Ajoutez la variable à côté du jeton, enregistrez, puis redémarrez le client :

"env": { "YNAB_API_KEY": "votre-jeton", "AVENIR_MCP_WRITE": "1" }

Codex CLI (TOML)

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 20 outils au lieu de 11.

	Lecture seule (défaut)	Avec AVENIR_MCP_WRITE=1
Outils listés	11	20
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

Si votre client ne sait pas vous poser la question

Certains clients ne savent pas vous poser une question (l’elicitation MCP). avenir-mcp remet alors à l’agent un code à usage unique, et c’est à l’agent de vous montrer les changements et d’attendre votre oui. Dans notre évaluation, un modèle sur huit, trompé par un mémo glissé dans une transaction, s’est servi seul d’un tel code, puis a annulé son changement. Pour que vous seul puissiez confirmer, ajoutez AVENIR_MCP_REQUIRE_ELICITATION=1 si votre client gère l’elicitation : les codes sont alors désactivés.

Chaque changement vous est montré avant d’être appliqué : voir Sécurité par conception.

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
Retirer	claude mcp remove avenir-mcp --scope user, ou supprimez l’entrée avenir-mcp de la configuration du client
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

• Votre première conversation : une visite guidée.
• Fonctionnalités : tout ce qu’avenir-mcp sait faire.
• Configuration : chaque variable d’environnement.