avenir-mcp — an unofficial MCP server for YNAB

Self-checked on every change against YNAB's API terms of 2025-05-28 (naming, attribution, YNAB's own image, a personal token for its owner only, the hourly limit); a weekly job turns the badge red when YNAB changes its terms. Listed by YNAB in its Works with YNAB directory, among third-party apps. Not endorsed by YNAB.

Built and tested against YNAB's API v1.87.0. A weekly YNAB API drift check compares it with the live specification and fails when YNAB publishes a new version.

🇬🇧 avenir-mcp (avenir is French for the future) lets an AI agent read your YNAB plan and help you plan what comes next.

🇫🇷 avenir-mcp permet à un agent IA de lire votre plan YNAB et de vous aider à préparer la suite.

Ask Claude — or any MCP client — about your plan in plain words: where the money went, what still needs a category, whether an account matches the bank, when money would run out. Every change is previewed, confirmed by you, and can be undone.

📖 Documentation: https://avenir-mcp.pages.dev/avenir-mcp/

English · Français · Español · Deutsch · Nederlands

All four come from the invented demo plan: the write above is replayed by python -m docsgen, so every line of it is what avenir-mcp answers today; then a real reply of Claude Sonnet, and the net worth and the forecast the documentation shows. The demo plays for thirty seconds and holds its last frame, which tells the whole story on its own: a reader whose system asks for less motion, or a viewer that does not animate, sees that frame instead.

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. They are named here only to say which service avenir-mcp works with.

avenir-mcp is for personal use on your own machine, with your own YNAB token. Running it as a public or shared server is not supported. It is provided as is, without warranty, and is not financial advice: you remain responsible for the changes you confirm. See the legal notice.

Why avenir-mcp

• Tools for tasks, not endpoints. Classify a month of transactions, reconcile an account, forecast your balance: one tool each, not a wrapper of YNAB's API.
• Read-only by default. Tools that change your plan exist only when you enable them.
• Preview, confirm, undo. Every write shows what will change and waits for your yes; undo_operation reverts it.
• Answers an agent can read. Currency units, short typed answers, pagination, errors that say what to fix, bank text treated as untrusted.
• Verified. 100 % line and branch coverage, and an evaluation where a real agent works on an invented plan: 25/25 tasks.

Install

You need a YNAB personal access token (YNAB → Account Settings → Developer Settings → New Token), and, except with the Claude Desktop extension, uv.

One click installs avenir-mcp read-only in Claude Desktop: open Settings → Extensions and drag the avenir-mcp.mcpb the button downloads onto that screen, then paste your token, which the extension keeps out of sight. Add AVENIR_MCP_WRITE=1, or tick Allow changes to your plans in the extension, to allow changes.

On Windows, or if a terminal is not where you are at home, the extension is the way in: no uv, no command, no file to edit. Numbered steps, from the download to a first answer: Install the Claude Desktop extension. The extension is attached by the release workflow, so a release published before that job existed carries none: while the latest release is one of those, the button gives GitHub's Not Found page, and installing by hand, below, is what works until the next release. The releases say which assets each one carries.

Cursor, LM Studio and VS Code install it read-only in one click too, from the buttons on the Install page. A README cannot carry those: GitHub drops a link an editor opens, so the button would lead nowhere.

Or by hand:

# Claude Code
claude mcp add avenir-mcp --env YNAB_API_KEY=your-token --env AVENIR_MCP_WRITE=1 -- uvx avenir-mcp

// Claude Desktop, Cursor: the mcpServers block of the client's configuration
{
  "mcpServers": {
    "avenir-mcp": {
      "command": "uvx",
      "args": ["avenir-mcp"],
      "env": { "YNAB_API_KEY": "your-token", "AVENIR_MCP_WRITE": "1" }
    }
  }
}

Drop AVENIR_MCP_WRITE to stay read-only. Other clients and every option: Install · Configuration.

Claude Code plugin

plugin/ is avenir-mcp as a Claude Code plugin: Claude Code asks for your YNAB token in the plugin's settings, keeps it out of sight, and starts the server from the plugin's own locked environment. From a clone: claude --plugin-dir plugin.

What you can ask

Walk-throughs with real answers: Use cases. Every tool, resource and prompt: Reference.

Development

git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcp
uv sync
just check        # lint, types, tests at 100 % coverage, vocabulary, lockfile
just docs-serve   # the documentation, live
just evaluate     # a real agent on the demo plan (uses your Claude plan)

Read AGENTS.md and CONTRIBUTING.md before opening a pull request. Security reports: SECURITY.md. Also: ARCHITECTURE.md, ROADMAP.md, GOVERNANCE.md and the code of conduct.

Privacy Policy

avenir-mcp is a program you run yourself, not a service: its publisher runs no server and receives none of your data. Your token is read from the environment, kept in memory as a secret value and sent only to YNAB; your plan's data is fetched when a tool needs it, kept in memory, and returned to your agent, which means the model provider your MCP client sends tool results to also sees it. Nothing is sold, and nothing goes to a third party this does not name. What is handled, how long it is kept and how to erase it: https://avenir-mcp.pages.dev/avenir-mcp/project/privacy/.

Licence

MIT.