Your YNAB budget, in plain words.

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

Why 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 nine 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.

Every change, on your terms

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.

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

Real answers, not prose

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

You: How did August go?

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

Share of each budget usedAugust 2026

Answer of get_budget_vs_actual on the demo budget

Show as a table

Category	Budgeted	Spent	used
Bills · Rent	950.00	950.00	100 %
Bills · Phone	20.00	19.99	100 %
Bills · Electricity	70.00	64.20	92 %
Everyday · Restaurants	120.00	89.10	74 %
Everyday · Transport	90.00	45.00	50 %
Everyday · Groceries	400.00	192.51	48 %
Fun · Subscriptions	15.00	13.49	90 %
Fun · Tennis	80.00	22.00	28 %
Savings goals · Holidays	200.00	0.00	0 %

Claude: August stayed within budget everywhere. Rent, phone and electricity used 90 % or more of theirs, subscriptions nearly as much, groceries about half. The 200.00 set aside for holidays is untouched.

The raw answer

get_budget_vs_actual — demo budget

[
  {
    "id": "cat-rent",
    "name": "Rent",
    "group": "Bills",
    "budgeted": 950.0,
    "actual": 950.0,
    "balance": 0.0,
    "utilization_pct": 100.0
  },
  {
    "id": "cat-power",
    "name": "Electricity",
    "group": "Bills",
    "budgeted": 70.0,
    "actual": 64.2,
    "balance": 5.8,
    "utilization_pct": 91.7
  },
  {
    "id": "cat-phone",
    "name": "Phone",
    "group": "Bills",
    "budgeted": 20.0,
    "actual": 19.99,
    "balance": 0.01,
    "utilization_pct": 99.9
  },
  {
    "id": "cat-groceries",
    "name": "Groceries",
    "group": "Everyday",
    "budgeted": 400.0,
    "actual": 192.51,
    "balance": 207.49,
    "utilization_pct": 48.1
  },
  {
    "id": "cat-restaurants",
    "name": "Restaurants",
    "group": "Everyday",
    "budgeted": 120.0,
    "actual": 89.1,
    "balance": 30.9,
    "utilization_pct": 74.2
  },
  {
    "id": "cat-transport",
    "name": "Transport",
    "group": "Everyday",
    "budgeted": 90.0,
    "actual": 45.0,
    "balance": 45.0,
    "utilization_pct": 50.0
  },
  {
    "id": "cat-tennis",
    "name": "Tennis",
    "group": "Fun",
    "budgeted": 80.0,
    "actual": 22.0,
    "balance": 58.0,
    "utilization_pct": 27.5
  },
  {
    "id": "cat-subscriptions",
    "name": "Subscriptions",
    "group": "Fun",
    "budgeted": 15.0,
    "actual": 13.49,
    "balance": 1.51,
    "utilization_pct": 89.9
  },
  {
    "id": "cat-holidays",
    "name": "Holidays",
    "group": "Savings goals",
    "budgeted": 200.0,
    "actual": 0.0,
    "balance": 200.0,
    "utilization_pct": 0.0
  }
]

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

Explore the documentation

Getting startedInstall in five minutes, then a guided first conversation.

GuidesClassify, reconcile, review a month, plan ahead — step by step.

ConceptsArchitecture, safety, confirmation, suggestions, forecasting.

ReferenceEvery tool: parameters, returns, cost, errors, example.