Your YNAB plan, 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 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.

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, what was spent and what is left. Here is that answer on the demo plan, drawn:

What is left in each categoryAugust 2026

Answer of get_budget_vs_actual on the demo plan

Show as a table

Category	Budgeted	Spent	Left
Bills · Rent	950.00	950.00	0.00
Bills · Electricity	64.20	64.20	0.00
Bills · Internet	29.99	29.99	0.00
Bills · Phone	19.99	19.99	0.00
Everyday · Groceries	400.00	192.51	207.49
Everyday · Transport	90.00	45.00	45.00
Everyday · Restaurants	120.00	89.10	30.90
Fun · Tennis	80.00	22.00	58.00
Fun · Subscriptions	13.49	13.49	0.00
Savings goals · Holidays	200.00	0.00	200.00

Claude: August 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,
    "actual": 950.0,
    "balance": 0.0,
    "utilization_pct": 100.0
  },
  {
    "id": "cat-power",
    "name": "Electricity",
    "group": "Bills",
    "budgeted": 64.2,
    "actual": 64.2,
    "balance": 0.0,
    "utilization_pct": 100.0
  },
  {
    "id": "cat-internet",
    "name": "Internet",
    "group": "Bills",
    "budgeted": 29.99,
    "actual": 29.99,
    "balance": 0.0,
    "utilization_pct": 100.0
  },
  {
    "id": "cat-phone",
    "name": "Phone",
    "group": "Bills",
    "budgeted": 19.99,
    "actual": 19.99,
    "balance": 0.0,
    "utilization_pct": 100.0
  },
  {
    "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": 13.49,
    "actual": 13.49,
    "balance": 0.0,
    "utilization_pct": 100.0
  },
  {
    "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 plan.

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.