Installatie

Deze pagina brengt je in ongeveer tien minuten van niets naar een werkende avenir-mcp. Elke stap eindigt met een controle, zodat je weet dat het gelukt is voordat je verdergaat.

1. uv installeren, het programma dat avenir-mcp uitvoert.
2. Een YNAB-token aanmaken, de toegang van avenir-mcp tot je plans.
3. Controleren of avenir-mcp start, één keer met de hand.
4. avenir-mcp aan je client toevoegen.
5. Controleren of het werkt, met een eerste vraag.
6. Wijzigingen toestaan, als de agent voor je mag opruimen.

Wat je nodig hebt

	Waarom	Waar je het vindt
Een YNAB-account	avenir-mcp leest en wijzigt jouw plans	app.ynab.com
Een MCP-client	de applicatie waarmee je praat; die start avenir-mcp	Claude Code, Claude Desktop, Cursor, VS Code…
uv	downloadt en draait avenir-mcp, en de Python die het nodig heeft, in een geïsoleerde omgeving	de volgende stap

Je hoeft Python niet te installeren, de repository niet te klonen en geen virtuele omgeving aan te maken: uv doet dat allemaal.

uv installeren

macOS / Linux

In een terminal:

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

Of met Homebrew: brew install uv.

Windows

In PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Of met WinGet: winget install --id=astral-sh.uv -e.

Sluit de terminal en open hem opnieuw, en controleer dan:

uv --version

Er verschijnt een versie, zoals uv 0.12.19. Command not found? Het installatieprogramma voegt uv alleen toe aan het PATH van nieuwe terminals: open een nieuwe. Details in de documentatie van uv.

Een YNAB-token aanmaken

1. Log in bij YNAB in een webbrowser op app.ynab.com – de mobiele apps tonen de ontwikkelaarsinstellingen niet.
2. Klik linksboven op je naam en dan op Account Settings.
3. Open Developer Settings.
4. Klik onder Personal Access Tokens op New Token, voer je YNAB-wachtwoord in en klik op Generate.
5. Kopieer het token dat bovenaan de pagina staat: een lange reeks letters, cijfers en streepjes. YNAB toont het maar één keer. Ben je het kwijt, maak dan een nieuw aan en trek het oude in.

Behandel het token als een wachtwoord

Een personal access token kan elk plan van je account lezen en wijzigen; YNAB biedt geen token dat alleen kan lezen. Plak het nooit in een chat met een AI, een gedeeld bestand, een issue of een repository. avenir-mcp logt het nooit en geeft het nooit terug in een antwoord.

Controleren of avenir-mcp start

Voordat je een client instelt, draai je avenir-mcp één keer met de hand. Zo wordt het gedownload en zie je dat het start.

macOS / Linux

YNAB_API_KEY=jouw-token uvx avenir-mcp

Windows

$env:YNAB_API_KEY = "jouw-token"; uvx avenir-mcp

De eerste keer worden avenir-mcp en Python gedownload: een paar seconden tot een minuut. Daarna wordt er niets getoond en keert het commando niet terug – dat hoort zo: avenir-mcp wacht tot een client met hem praat. Druk op Ctrl+C om het te stoppen.

Verschijnt er in plaats daarvan een fout? Zie Probleemoplossing.

avenir-mcp aan je client toevoegen

Kies je client. Deze configuraties zijn alleen lezen: avenir-mcp kan vragen beantwoorden maar niets wijzigen. Wijzigingen toestaan komt daarna.

Claude Code

In een terminal:

claude mcp add avenir-mcp --scope user \
  --env YNAB_API_KEY=jouw-token \
  -- uvx avenir-mcp

Deel	Betekenis
claude mcp add avenir-mcp	een MCP-server met de naam avenir-mcp registreren
--scope user	voor al je projecten; laat het weg om hem alleen voor de huidige map te registreren
--env YNAB_API_KEY=…	de omgeving waarmee avenir-mcp start
--	wat volgt is het commando dat de server start
uvx avenir-mcp	dat commando

Claude Code bewaart dit, token inbegrepen, in ~/.claude.json, alleen leesbaar voor jou.

Claude Desktop

1. Open Claude Desktop, dan Settings → Developer → Edit Config. Zo opent claude_desktop_config.json:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Is het bestand leeg, plak dan dit alles. Staan er al servers in, voeg dan alleen het blok "avenir-mcp": { … } toe binnen de bestaande mcpServers, met een komma na de vorige regel.

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

3. Sla op, sluit Claude Desktop dan helemaal af – ⌘Q op macOS, of via het pictogram in het systeemvak op Windows – en open het opnieuw.

Cursor

1. Maak of open ~/.cursor/mcp.json (alle projecten) of .cursor/mcp.json in een project, en voeg toe:

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

2. Open Cursor Settings → MCP en controleer dat avenir-mcp aanstaat.

VS Code

1. Maak .vscode/mcp.json in je werkruimte:

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

2. Voer het commando MCP: List Servers uit, kies avenir-mcp en dan Start Server.
3. Gebruik het vanuit Copilot Chat in de modus Agent.

Gemini CLI

1. Open ~/.gemini/settings.json (maak het aan als dat nodig is) en voeg toe:

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

2. Start gemini en typ /mcp: avenir-mcp staat erbij met zijn tools. Het model is dat van Gemini CLI.

Codex CLI

1. Open ~/.codex/config.toml (maak het aan als dat nodig is) en voeg toe:

   [mcp_servers.avenir]
   command = "uvx"
   args = ["avenir-mcp"]
   env = { YNAB_API_KEY = "jouw-token" }

2. Start codex en typ /mcp: avenir-mcp staat erbij met zijn tools. Het model is dat van Codex.

LM Studio

Voor een model dat op je eigen computer draait – zie Een model kiezen.

1. Open in LM Studio het tabblad Program van de rechterzijbalk, dan Install → Edit mcp.json, en voeg toe:

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

2. Sla op, laad een model dat toolgebruik ondersteunt en begin een chat: LM Studio vraagt het vóór elke toolaanroep.

Andere clients

Elke MCP-client die servers via stdio start, werkt. Geef hem:

Instelling	Waarde
commando	uvx
argumenten	avenir-mcp
omgeving	YNAB_API_KEY = je token

Voor clients die in plaats daarvan met een URL verbinden, zie Via HTTP draaien.

„uvx not found“ in een desktopapplicatie

Grafische applicaties zien niet altijd het PATH van je terminal. Vindt de client uvx niet, vervang dan "uvx" door het volledige pad, dat je krijgt met which uvx (macOS, Linux) of where uvx (Windows) – bijvoorbeeld "/Users/<jij>/.local/bin/uvx".

Controleren of het werkt

Claude Code

claude mcp list

avenir-mcp hoort verbonden te zijn:

avenir-mcp: uvx avenir-mcp - ✔ Connected

Start dan claude en typ /mcp: avenir-mcp toont zijn 12 tools.

Andere clients

Open de lijst met MCP-servers of tools van de client: avenir-mcp hoort te draaien, met 12 tools.

Vraag nu in een nieuw gesprek: „Toon mijn YNAB-plans.“ De agent roept list_plans aan – je client vraagt je misschien om toestemming – en antwoordt met hun namen. Hier het demoplan dat in deze hele documentatie wordt gebruikt:

list_plans

[
  {
    "id": "demo-budget",
    "name": "Demohuishouden",
    "first_month": "2026-06-01",
    "last_month": "2026-09-01"
  }
]

avenir-mcp werkt. Ga verder met je eerste gesprek, of sta eerst wijzigingen toe.

Wijzigingen toestaan

Om de agent transacties te laten categoriseren, geld tussen categorieën te laten verschuiven of rekeningen te laten afstemmen, voeg je AVENIR_MCP_WRITE=1 toe aan de omgeving van avenir-mcp.

Claude Code

Verwijder avenir-mcp en voeg het opnieuw toe met de extra variabele:

claude mcp remove avenir-mcp --scope user
claude mcp add avenir-mcp --scope user \
  --env YNAB_API_KEY=jouw-token \
  --env AVENIR_MCP_WRITE=1 \
  -- uvx avenir-mcp

JSON-configuraties

Voeg de variabele toe naast het token, sla op en herstart de client:

"env": { "YNAB_API_KEY": "jouw-token", "AVENIR_MCP_WRITE": "1" }

Codex CLI (TOML)

Voeg de variabele toe naast het token in ~/.codex/config.toml en herstart Codex:

env = { YNAB_API_KEY = "jouw-token", AVENIR_MCP_WRITE = "1" }

De waarde moet precies 1 zijn. Controleer: de client toont nu 25 tools in plaats van 12.

	Alleen lezen (standaard)	Met AVENIR_MCP_WRITE=1
Getoonde tools	12	25
Categoriseren, budgetteren, afstemmen, aanmaken	—	met voorbeeld, door jou bevestigd, ongedaan te maken
Als de agent iets verkeerd begrijpt	er kan niets veranderen	een wijziging die je hebt bevestigd en ongedaan kunt maken

Als je client je niets kan vragen

Sommige clients kunnen je geen vraag stellen (MCP-elicitation). avenir-mcp geeft de agent dan een eenmalige code, en het is aan de agent om je de wijzigingen te laten zien en op je ja te wachten. In onze evaluatie gebruikte één model op de acht, misleid door een omschrijving die in een transactie was geplant, zo’n code op eigen houtje, en maakte zijn wijziging daarna ongedaan. Wil je dat alleen jij kunt bevestigen, voeg dan AVENIR_MCP_REQUIRE_ELICITATION=1 toe als je client elicitation ondersteunt: codes zijn dan uitgeschakeld.

Elke wijziging krijg je te zien voordat ze wordt toegepast: zie Veilig door ontwerp.

Bijwerken, verwijderen, intrekken

Om te	Doe je
Bijwerken	uvx haalt zelf af en toe nieuwe versies op; forceer het met uvx --refresh avenir-mcp
Verwijderen	claude mcp remove avenir-mcp --scope user, of verwijder het item avenir-mcp uit de configuratie van de client
Opruimen	het enige bestand van avenir-mcp op je computer is zijn journaal, in ~/.local/state/avenir-mcp/
Het token intrekken	YNAB → Account Settings → Developer Settings → Revoke naast het token

Verder

• Je eerste gesprek: een begeleide rondleiding.
• Functies: alles wat avenir-mcp kan.
• Configuratie: elke omgevingsvariabele.