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.
- Install uv, the tool that runs avenir-mcp.
- Get a YNAB token, avenir-mcp’s access to your plans.
- Check that avenir-mcp starts, by hand, once.
- Add avenir-mcp to your client.
- Check it works with a first question.
- Allow changes, if you want the agent to tidy up for you.
What you need
Section titled “What you need”| Why | Where to get it | |
|---|---|---|
| A YNAB account | avenir-mcp reads and changes your plans | 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
Section titled “Install uv”In a terminal:
curl -LsSf https://astral.sh/uv/install.sh | shOr, with Homebrew: brew install uv.
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 --versionIt 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
Section titled “Get a YNAB token”- Sign in to YNAB in a web browser at app.ynab.com — the mobile apps do not show developer settings.
- Click your name at the top left, then Account Settings.
- Open Developer Settings.
- Under Personal Access Tokens, click New Token, enter your YNAB password, then Generate.
- 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.
Install the Claude Desktop extension
Section titled “Install the Claude Desktop extension”One file installs avenir-mcp, the Python it runs on and the settings it needs. There is no terminal and no configuration file in this section, and no step of it is different on Windows, macOS or Linux except where it says so.
Download for Claude DesktopThe file is always the one of the newest release; which version it installs is written inside it, and the steps below are the same whichever that is.
-
Install Claude Desktop if you have not already, from claude.ai/download, and open it once.
-
Download the extension with the button above, or with this link. It weighs about 17 kB and goes to your Downloads folder as
avenir-mcp.mcpb.On Windows, Edge or Chrome may say that the file isn’t commonly downloaded. That warning is about how rare the file is, not about what is in it: click the three dots beside the download, then Keep. What you can check about the file instead is in SECURITY.md.
-
Drag the file onto Settings → Extensions. Open Claude Desktop, then Settings → Extensions: that screen lists the extensions you have, and it is where the file installs. Take
avenir-mcp.mcpbfrom your Downloads folder, or from the browser’s download list, and drop it on that screen. The install dialog opens.Double-clicking the file may work as well, if your system already opens
.mcpbfiles with Claude Desktop. If instead Windows asks which application to open the file with, close that window:.mcpbfiles have no application associated with them, and searching forclaude.exefinds nothing. Drag the file onto the Extensions screen instead.Neither works? On that same screen, open Advanced settings and, under Extension Developer, Install Extension…; pick the
.mcpbfrom your Downloads folder. -
Install it. The dialog names the extension, avenir-mcp for YNAB, and says what it does. Click Install.
-
Paste your token in YNAB personal access token — the one from the step above.
Ctrl+Von Windows and Linux,⌘+Von macOS. The box hides it as you type; Claude Desktop keeps it where your system keeps passwords, and it is written in no file you can open. -
Leave Allow changes to your plans off, then Save. avenir-mcp answers questions and changes nothing until you turn that on, which you can do at any time, in the same place.
-
Check it is there. Settings → Extensions lists avenir-mcp for YNAB, with its switch on.
-
Ask it something. In a new conversation: “List my YNAB plans.” Claude asks you to allow the tool the first time; allow it, and the answer names your plans. The very first answer takes a few seconds longer than the ones after it, while Claude Desktop fetches Python and avenir-mcp.
That is the whole installation. The rest of this page is for the other clients and for installing by hand; skip to your first conversation, or to allow changes when you want the agent to tidy up for you.
| To | Do |
|---|---|
| Change the token, or allow changes | Settings → Extensions → avenir-mcp for YNAB |
| Update | download the extension again and drop it on the Settings → Extensions screen, over the installed one; the link always gives the newest release |
| Remove it | Settings → Extensions, then remove it; the token goes with it |
Check that avenir-mcp starts
Section titled “Check that avenir-mcp starts”Before configuring a client, run avenir-mcp once by hand. This downloads it and proves that it starts.
YNAB_API_KEY=your-token uvx avenir-mcp$env:YNAB_API_KEY = "your-token"; uvx avenir-mcpThe 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
Section titled “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. Cursor, LM Studio and VS Code install it in one click, from the button at the top of their tab.
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.
The extension is the short way, and the one with no terminal: Install the Claude Desktop extension.
Or by hand, if you would rather write the configuration yourself:
- 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
- macOS:
- If the file is empty, paste all of this. If it already lists servers, add only
the
"avenir-mcp": { … }block inside the existingmcpServers, with a comma after the previous entry.{"mcpServers": {"avenir-mcp": {"command": "uvx","args": ["avenir-mcp"],"env": { "YNAB_API_KEY": "your-token" }}}} - Save, then quit Claude Desktop completely — ⌘Q on macOS, or from the tray icon on Windows — and reopen it.
- Click the button: Cursor asks you to confirm, then adds
avenir-mcpto its servers. - Open Cursor Settings → MCP, replace
your-tokenwith the token you copied, and check thatavenir-mcpis switched on.
Or by hand: 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" } } }}- Click the button: VS Code asks you to confirm, then asks for your token in a password box and keeps it in its own secret storage.
- Use avenir-mcp from Copilot Chat in Agent mode.
Or by hand: create .vscode/mcp.json in your workspace. VS Code asks for the token
there too, so the file never holds it: a file of a workspace is easy to add to a
repository by mistake.
{ "inputs": [ { "type": "promptString", "id": "ynab-token", "description": "YNAB personal access token", "password": true } ], "servers": { "avenir-mcp": { "type": "stdio", "command": "uvx", "args": ["avenir-mcp"], "env": { "YNAB_API_KEY": "${input:ynab-token}" } } }}Then run the command MCP: List Servers, select avenir-mcp, then Start Server.
- Open
~/.gemini/settings.json(create it if needed) and add:{"mcpServers": {"avenir-mcp": {"command": "uvx","args": ["avenir-mcp"],"env": { "YNAB_API_KEY": "your-token" }}}} - Start
geminiand type/mcp:avenir-mcpis listed with its tools. The model is the one Gemini CLI uses.
- Open
~/.codex/config.toml(create it if needed) and add:[mcp_servers.avenir]command = "uvx"args = ["avenir-mcp"]env = { YNAB_API_KEY = "your-token" } - Start
codexand type/mcp:avenir-mcpis listed with its tools. The model is the one Codex uses.
For a model running on your own machine — see Choose a model.
- Click the button: LM Studio asks you to confirm, then adds
avenir-mcpto itsmcp.json. - Open the Program tab of the right-hand sidebar, then Install → Edit mcp.json,
and replace
your-tokenwith the token you copied. - Save, load a model that supports tool use, and start a chat: LM Studio asks before each tool call.
Or by hand: add this to the same mcp.json:
{ "mcpServers": { "avenir-mcp": { "command": "uvx", "args": ["avenir-mcp"], "env": { "YNAB_API_KEY": "your-token" } } }}Any MCP client that starts servers over stdio works. Give it:
| Setting | Value |
|---|---|
| command | uvx |
| arguments | avenir-mcp |
| environment | YNAB_API_KEY = your token |
To run it in a container instead, build the image from the Dockerfile at the root
of the repository with docker build -t avenir-mcp ., then give the client docker
as the command and run -i --rm -e YNAB_API_KEY avenir-mcp as the arguments, so
that the token travels in the environment rather than on a command line.
For clients that connect to a URL instead, see Run over HTTP.
Check it works
Section titled “Check it works”claude mcp listavenir-mcp should be connected:
avenir-mcp: uvx avenir-mcp - ✔ ConnectedThen start claude and type /mcp: avenir-mcp shows its 19 tools.
Open the client’s list of MCP servers or tools: avenir-mcp should be running, with 19
tools.
Now ask, in a new conversation: “List my YNAB plans.” The agent calls
list_plans — your client may ask you to
allow it — and answers with their names. Here, the demo plan used throughout this
documentation:
[ { "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
Section titled “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.
Installed from the extension: open Settings → Extensions → avenir-mcp for YNAB, turn Allow changes to your plans on, save, and restart Claude Desktop. The extension sets the variable for you, so there is nothing to type.
Remove avenir-mcp and add it again with the extra variable:
claude mcp remove avenir-mcp --scope userclaude mcp add avenir-mcp --scope user \ --env YNAB_API_KEY=your-token \ --env AVENIR_MCP_WRITE=1 \ -- uvx avenir-mcpAdd the variable next to the token, save, then restart the client:
"env": { "YNAB_API_KEY": "your-token", "AVENIR_MCP_WRITE": "1" }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 32 tools instead of 19.
| Read-only (default) | With AVENIR_MCP_WRITE=1 |
|
|---|---|---|
| Tools listed | 19 | 32 |
| Classify, budget, reconcile, create | — | previewed, confirmed by you, undoable |
| If the agent misunderstands | nothing can change | a change you confirmed, which you can undo |
Every change is shown to you before it is applied: see Safety by design.
Update, remove, revoke
Section titled “Update, remove, revoke”| To | Do |
|---|---|
| Update | uvx fetches new releases by itself from time to time; force it with uvx --refresh avenir-mcp. The Claude Desktop extension is updated by downloading it again and dropping it on the Settings → Extensions screen, over the installed one |
| Remove | claude mcp remove avenir-mcp --scope user, or delete the avenir-mcp entry from the client’s configuration. The extension is removed from Settings → Extensions, token included |
| 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 |
- Your first conversation: a guided tour.
- Features: everything avenir-mcp can do.
- Configuration: every environment variable.
Unofficial project. 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. avenir-mcp is provided as is, without warranty, and is not financial advice. Legal notice · Privacy