Skip to content

Unofficial open-source MCP server for YNAB

Your YNAB plan, in plain words.

avenir-mcp lets Claude and other AI agents read, classify, reconcile and forecast your plan. Read-only by default; every change is previewed, confirmed by you, and can be undone.

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

Works withClaude CodeClaude DesktopCursorVS CodeGemini CLICodex CLILM Studio

17
tools, each doing a whole task
100 %
line and branch coverage
9 / 9
tasks passed by a real agent
1–2
YNAB requests per call, most tools

Works with YNAB

Listed by YNAB in its Works with YNAB directory, among third-party apps. Not endorsed by YNAB.

A 20-second tour of avenir-mcp: a question about an overspent category, four tools reading the plan at once, the exact fix previewed, confirmed and undoable, and the command that installs avenir-mcp.

Tools for tasks, not endpoints

Classify a month of transactions, reconcile an account with the bank, forecast the balance, review a month: each is one tool, not ten API calls for the agent to chain.

Read-only by default

The thirteen write tools are neither listed nor callable until you set AVENIR_MCP_WRITE=1. An agent cannot change what it cannot see.

Answers an agent can read

Currency units, never milliunits. Typed output schemas with a description for every field, pagination, and errors that say what to fix.

Light on YNAB's quota

A local copy of your transactions, refreshed by delta sync: most tools cost one or two of the 200 requests YNAB allows per hour.

Tracks YNAB's API

Built and tested against the YNAB API version pinned in the repository. A weekly check compares it with the live specification, so a change at YNAB cannot pass unnoticed.

  1. 1

    Preview

    avenir-mcp computes the exact change and shows it. Nothing is written yet.

  2. 2

    Confirm

    You say yes in your client, or with a one-time code bound to that preview.

  3. 3

    Undo

    Every applied change is journaled; undo restores it without overwriting later work.

One conversation, in thirty seconds. Asked how the month is going and where the room is, the agent calls four read-only tools at the same time: Month summary, Every category, Budget vs spent and Three months. It answers that Restaurants is the only category over budget: 166.50 spent of 144.00 available (120.00 budgeted + 24.00 left from earlier months), 138.8 %, available −22.50; that its spending rose 113.70 → 119.90 → 166.50 over three months; and that 80.00 is left in Tennis and 411.90 in Groceries. It offers to cover the 22.50 from Tennis, which has nothing spent yet. The user answers “Cover it from Tennis.”, and move_money shows a preview that changes nothing: Tennis budgeted 80.00 → 57.50, Restaurants budgeted 120.00 → 142.50, available −22.50 → 0.00, exactly on budget, with a Cancel button, a Confirm button, and the reminder that nothing changes until you confirm and that any change can be undone.One conversation, in thirty seconds. Asked how the month is going and where the room is, the agent calls four read-only tools at the same time: Month summary, Every category, Budget vs spent and Three months. It answers that Restaurants is the only category over budget: 166.50 spent of 144.00 available (120.00 budgeted + 24.00 left from earlier months), 138.8 %, available −22.50; that its spending rose 113.70 → 119.90 → 166.50 over three months; and that 80.00 is left in Tennis and 411.90 in Groceries. It offers to cover the 22.50 from Tennis, which has nothing spent yet. The user answers “Cover it from Tennis.”, and move_money shows a preview that changes nothing: Tennis budgeted 80.00 → 57.50, Restaurants budgeted 120.00 → 142.50, available −22.50 → 0.00, exactly on budget, with a Cancel button, a Confirm button, and the reminder that nothing changes until you confirm and that any change can be undone.

Categories, amounts, reconciliations and created transactions can all be undone. How it works: Confirmation and Journal and undo.

Tools return structured data the agent can rely on — and put into plain words for you.

You: How did last month go?

The agent calls get_budget_vs_actual with {"month": "2026-08-01"} and gets, for every category, what was budgeted, what was spent and what is left. Here is that answer on the demo plan, drawn:

What is left in each categoryLast month
BillsHome insurance315.00Rent0.00Electricity0.00Internet0.00Phone0.00EverydayRestaurants24.00Groceries11.90Transport0.00FunTennis0.00Subscriptions0.00Savings goalsEmergency fund1,200.00Holidays600.00

Answer of get_budget_vs_actual on the demo plan

Show as a table
CategoryBudgetedSpentLeft
Bills · Home insurance105.000.00315.00
Bills · Rent950.00950.000.00
Bills · Electricity64.2064.200.00
Bills · Internet29.9929.990.00
Bills · Phone19.9919.990.00
Everyday · Restaurants120.00119.9024.00
Everyday · Groceries400.00397.6011.90
Everyday · Transport45.0045.000.00
Fun · Tennis22.0022.000.00
Fun · Subscriptions13.4913.490.00
Savings goals · Emergency fund400.000.001,200.00
Savings goals · Holidays200.000.00600.00

Claude: Last month stayed within budget everywhere: no category is overspent. The bills are paid, 207.49 is left for groceries and 58.00 for tennis, and the 200.00 set aside for holidays is untouched.

The raw answer
get_budget_vs_actual — demo plan
[
{
"id": "cat-rent",
"name": "Rent",
"group": "Bills",
"budgeted": 950.0,
"carried_over": 0.0,
"actual": 950.0,
"balance": 0.0,
"utilization_pct": 100.0
},
{
"id": "cat-power",
"name": "Electricity",
"group": "Bills",
"budgeted": 64.2,
"carried_over": 0.0,
"actual": 64.2,
"balance": 0.0,
"utilization_pct": 100.0
},
{
"id": "cat-internet",
"name": "Internet",
"group": "Bills",
"budgeted": 29.99,
"carried_over": 0.0,
"actual": 29.99,
"balance": 0.0,
"utilization_pct": 100.0
},
{
"id": "cat-phone",
"name": "Phone",
"group": "Bills",
"budgeted": 19.99,
"carried_over": 0.0,
"actual": 19.99,
"balance": 0.0,
"utilization_pct": 100.0
},
{
"id": "cat-insurance",
"name": "Home insurance",
"group": "Bills",
"budgeted": 105.0,
"carried_over": 210.0,
"actual": 0.0,
"balance": 315.0,
"utilization_pct": 0.0
},
{
"id": "cat-groceries",
"name": "Groceries",
"group": "Everyday",
"budgeted": 400.0,
"carried_over": 9.5,
"actual": 397.6,
"balance": 11.9,
"utilization_pct": 99.4
},
{
"id": "cat-restaurants",
"name": "Restaurants",
"group": "Everyday",
"budgeted": 120.0,
"carried_over": 23.9,
"actual": 119.9,
"balance": 24.0,
"utilization_pct": 99.9
},
{
"id": "cat-transport",
"name": "Transport",
"group": "Everyday",
"budgeted": 45.0,
"carried_over": 0.0,
"actual": 45.0,
"balance": 0.0,
"utilization_pct": 100.0
},
{
"id": "cat-tennis",
"name": "Tennis",
"group": "Fun",
"budgeted": 22.0,
"carried_over": 0.0,
"actual": 22.0,
"balance": 0.0,
"utilization_pct": 100.0
},
{
"id": "cat-subscriptions",
"name": "Subscriptions",
"group": "Fun",
"budgeted": 13.49,
"carried_over": 0.0,
"actual": 13.49,
"balance": 0.0,
"utilization_pct": 100.0
},
{
"id": "cat-holidays",
"name": "Holidays",
"group": "Savings goals",
"budgeted": 200.0,
"carried_over": 400.0,
"actual": 0.0,
"balance": 600.0,
"utilization_pct": 0.0
},
{
"id": "cat-buffer",
"name": "Emergency fund",
"group": "Savings goals",
"budgeted": 400.0,
"carried_over": 800.0,
"actual": 0.0,
"balance": 1200.0,
"utilization_pct": 0.0
}
]

Every example in this documentation is a real answer from avenir-mcp on an invented demo plan.

Tell us the question you would like to ask your budget in Discussions → Ideas. Help with using avenir-mcp is in Discussions → Q&A. Never post a real amount, a real account or your 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