Avenir Mcp

io.github.mathbealv0.2.0Updated Sep 30, 2026

Unofficial MCP server for YNAB: read-only by default, every change previewed and undoable.

VerifiedSTDIODesktop onlyCloud & Infrastructure

Installation

In SourceWeft

  1. Open Avenir Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

avenir-mcp — an unofficial MCP server for YNAB

[Works with YNAB] [YNAB API terms: self-checked]

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. Not reviewed or endorsed by YNAB.

[quality] [MCP Inspector] [docs]

[PyPI] [python] [coverage] [types] [docstrings] [code style] [licence] [last commit]

🇬🇧 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://mathbeal.github.io/avenir-mcp/

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

[Asked how the September budget is doing, the agent reads the month with two read-only tools and answers: one category over budget, Restaurants by 22.50, everything else on track.] [forecast_balance on the demo plan: the month-end balance rises from September to December, with each month's lowest day and a yearly insurance payment scheduled on 20 October.]

Both come from the invented demo plan: a real reply of Claude Sonnet, and the forecast the documentation shows.

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: 19/19 tasks.

Install

You need uv and a YNAB personal access token (YNAB → Account Settings → Developer Settings → New Token).

[Install in VS Code] [Install in Cursor]

One click installs avenir-mcp read-only: VS Code asks for your token in a password box and keeps it in its secret storage; in Cursor, replace your-token in the server's settings. Add AVENIR_MCP_WRITE=1 to allow changes.

Or by hand:

bash
# Claude Codeclaude mcp add avenir-mcp --env YNAB_API_KEY=your-token --env AVENIR_MCP_WRITE=1 -- uvx avenir-mcp
jsonc
// 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.

What you can ask

You askavenir-mcp
"Which category is overspent this month?"get_monthly_summary — totals and overspent categories
"Categorise what is pending."suggest_categories, then apply_categories after your yes
"Split this receipt: 81.15 groceries, 5.25 household."split_transaction — one transaction across categories, after your yes
"Which transaction is my 86.40 receipt from the 12th?"find_transactions — by dates, exact amount and account, categorised or not
"My bank shows 3,440.80. Does YNAB agree?"reconcile_account — explains the gap, changes nothing until it matches
"Will I go below zero before December?"forecast_balance — month by month, with its assumptions
"Move 30 from Tennis to Restaurants."set_category_budget, previewed and undoable
"Undo that."undo_operation

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

Development

bash
git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcpuv syncjust check        # lint, types, tests at 100 % coverage, vocabulary, lockfilejust docs-serve   # the documentation, livejust 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.

Licence

MIT.

Source: README.md at commit b1225d3

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.2.0LatestSep 30, 2026