Install

This page takes you from nothing to a working avenir-mcp, in about ten minutes. Each step ends with a check, so you know it worked before moving on.

1. Install uv, the tool that runs avenir-mcp.
2. Get a YNAB token, avenir-mcp’s access to your budgets.
3. Check that avenir-mcp starts, by hand, once.
4. Add avenir-mcp to your client.
5. Check it works with a first question.
6. Allow changes, if you want the agent to tidy up for you.

What you need

	Why	Where to get it
A YNAB account	avenir-mcp reads and changes your budgets	app.ynab.com
An MCP client	the application you talk to; it starts avenir-mcp	Claude Code, Claude Desktop, Cursor, VS Code…
uv	downloads and runs avenir-mcp, and the Python it needs, in an isolated environment	the next step

You do not need to install Python, clone the repository or create a virtual environment: uv does all of it.

Install uv

macOS / Linux

In a terminal:

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

Or, with Homebrew: brew install uv.

Windows

In PowerShell:

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

Or, with WinGet: winget install --id=astral-sh.uv -e.

Close and reopen the terminal, then check:

uv --version

It prints a version, such as uv 0.12.19. Command not found? The installer adds uv to the PATH of new terminals only: open a new one. Details in uv’s documentation.

Get a YNAB token

1. Sign in to YNAB in a web browser at app.ynab.com — the mobile apps do not show developer settings.
2. Click your name at the top left, then Account Settings.
3. Open Developer Settings.
4. Under Personal Access Tokens, click New Token, enter your YNAB password, then Generate.
5. Copy the token shown at the top of the page: a long string of letters, digits and dashes. YNAB shows it only once. If you lose it, create another and revoke the old one.

Treat the token like a password

A personal access token can read and change every budget of your account; YNAB offers no read-only token. Never paste it into a chat with an AI, a shared file, an issue or a repository. avenir-mcp never logs it and never returns it in an answer.

Check that avenir-mcp starts

Before configuring a client, run avenir-mcp once by hand. This downloads it and proves that it starts.

macOS / Linux

YNAB_API_KEY=your-token uvx avenir-mcp

Windows

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

The first run downloads avenir-mcp and Python: a few seconds to a minute. Then nothing is printed and the command does not return — that is expected: avenir-mcp waits for a client to talk to it. Press Ctrl+C to stop it.

An error is printed instead? See Troubleshooting.

Add avenir-mcp to your client

Pick your client. These configurations are read-only: avenir-mcp can answer questions but change nothing. Allow changes comes after.

Claude Code

In a terminal:

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

Part	Meaning
claude mcp add avenir-mcp	register an MCP server named avenir-mcp
--scope user	for all your projects; leave it out to register it for the current folder only
--env YNAB_API_KEY=…	the environment avenir-mcp starts with
--	what follows is the command that starts the server
uvx avenir-mcp	that command

Claude Code keeps this, token included, in ~/.claude.json, readable by you only.

Claude Desktop

1. Open Claude Desktop, then Settings → Developer → Edit Config. This opens claude_desktop_config.json:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. If the file is empty, paste all of this. If it already lists servers, add only the "avenir-mcp": { … } block inside the existing mcpServers, with a comma after the previous entry.

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

3. Save, then quit Claude Desktop completely — ⌘Q on macOS, or from the tray icon on Windows — and reopen it.

Cursor

1. Create or open ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in a project, and add:

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

2. Open Cursor Settings → MCP and check that avenir-mcp is switched on.

VS Code

1. Create .vscode/mcp.json in your workspace:

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

2. Run the command MCP: List Servers, select avenir-mcp, then Start Server.
3. Use it from Copilot Chat in Agent mode.

Gemini CLI

1. Open ~/.gemini/settings.json (create it if needed) and add:

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

2. Start gemini and type /mcp: avenir-mcp is listed with its tools. The model is the one Gemini CLI uses.

Codex CLI

1. Open ~/.codex/config.toml (create it if needed) and add:

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

2. Start codex and type /mcp: avenir-mcp is listed with its tools. The model is the one Codex uses.

LM Studio

For a model running on your own machine — see Choose a model.

1. In LM Studio, open the Program tab of the right-hand sidebar, then Install → Edit mcp.json, and add:

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

2. Save, load a model that supports tool use, and start a chat: LM Studio asks before each tool call.

Other clients

Any MCP client that starts servers over stdio works. Give it:

Setting	Value
command	uvx
arguments	avenir-mcp
environment	YNAB_API_KEY = your token

For clients that connect to a URL instead, see Run over HTTP.

“uvx not found” in a desktop application

Graphical applications do not always see the PATH of your terminal. If the client cannot find uvx, replace "uvx" with its full path, given by which uvx (macOS, Linux) or where uvx (Windows) — for instance "/Users/<you>/.local/bin/uvx".

Check it works

Claude Code

claude mcp list

avenir-mcp should be connected:

avenir-mcp: uvx avenir-mcp - ✔ Connected

Then start claude and type /mcp: avenir-mcp shows its 9 tools.

Other clients

Open the client’s list of MCP servers or tools: avenir-mcp should be running, with 9 tools.

Now ask, in a new conversation: “List my YNAB budgets.” The agent calls list_plans — your client may ask you to allow it — and answers with their names. Here, the demo budget used throughout this documentation:

list_plans

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

avenir-mcp works. Continue with your first conversation, or allow changes first.

Allow changes

To let the agent classify transactions, move money between categories or reconcile accounts, add AVENIR_MCP_WRITE=1 to avenir-mcp’s environment.

Claude Code

Remove avenir-mcp and add it again with the extra variable:

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

JSON configurations

Add the variable next to the token, save, then restart the client:

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

Codex CLI (TOML)

Add the variable next to the token in ~/.codex/config.toml, then restart Codex:

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

The value must be exactly 1. Check: the client now lists 20 tools instead of 11.

	Read-only (default)	With AVENIR_MCP_WRITE=1
Tools listed	11	20
Classify, budget, reconcile, create	—	previewed, confirmed by you, undoable
If the agent misunderstands	nothing can change	a change you confirmed, which you can undo

If your client cannot ask you

Some clients cannot put a question to you (MCP elicitation). avenir-mcp then gives the agent a single-use code, and it is up to the agent to show you the changes and wait for your yes. In our evaluation, one model out of eight, misled by a memo planted in a transaction, used such a code on its own, then undid its change. So that only you can confirm, add AVENIR_MCP_REQUIRE_ELICITATION=1 if your client supports elicitation: codes are then disabled.

Every change is shown to you before it is applied: see Safety by design.

Update, remove, revoke

To	Do
Update	uvx fetches new releases by itself from time to time; force it with uvx --refresh avenir-mcp
Remove	claude mcp remove avenir-mcp --scope user, or delete the avenir-mcp entry from the client’s configuration
Clean up	avenir-mcp’s only file on your machine is its journal, in ~/.local/state/avenir-mcp/
Revoke the token	YNAB → Account Settings → Developer Settings → Revoke next to the token

Next

• Your first conversation: a guided tour.
• Features: everything avenir-mcp can do.
• Configuration: every environment variable.