Skip to content

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

In a terminal:

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

Or, with Homebrew: brew install uv.

Close and reopen the terminal, then check:

Terminal window
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.

  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.

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 Desktop

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

  1. Install Claude Desktop if you have not already, from claude.ai/download, and open it once.

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

  3. 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.mcpb from 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 .mcpb files with Claude Desktop. If instead Windows asks which application to open the file with, close that window: .mcpb files have no application associated with them, and searching for claude.exe finds 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 .mcpb from your Downloads folder.

  4. Install it. The dialog names the extension, avenir-mcp for YNAB, and says what it does. Click Install.

  5. Paste your token in YNAB personal access token — the one from the step above. Ctrl + V on Windows and Linux, ⌘ + V on 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.

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

  7. Check it is there. Settings → Extensions lists avenir-mcp for YNAB, with its switch on.

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

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

Terminal window
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.

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:

Terminal window
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.

Terminal window
claude mcp list

avenir-mcp should be connected:

avenir-mcp: uvx avenir-mcp - ✔ Connected

Then start claude and type /mcp: avenir-mcp shows its 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:

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.

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.

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.

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

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