Data and sync

Amounts

YNAB stores every amount as an integer number of milliunits: 1.00 is 1000, −12.34 is -12340. avenir-mcp converts at the boundary and never shows milliunits to the agent:

Direction	Rule
YNAB → agent	milliunits / 1000
agent → YNAB	round(amount × 1000): 111.32 becomes exactly 111320

Sums, differences and prorating are computed in milliunits, then converted once, so no rounding error can create or lose a cent. Amounts are in the budget’s own currency; spending is negative, money in positive.

Talking to YNAB

client.py is the only module that calls YNAB’s API:

Base URL	https://api.ynab.com/v1, or AVENIR_MCP_YNAB_URL
Authentication	Authorization: Bearer <YNAB_API_KEY> on every request
Methods used	GET to read; PATCH, POST and DELETE on transactions, categories and month budgets
Errors	any 4xx or 5xx comes back as Error calling tool '<tool>': YNAB <status>: <detail>, with YNAB’s own explanation

plan_id accepts last-used, which YNAB resolves to the plan you opened last.

Plans, formerly budgets

YNAB renamed budgets to plans, in its apps and in its API: the specification now documents only /plans paths. avenir-mcp follows it: its client calls /plans, and its tools say list_plans and plan_id. The word budget stays where YNAB keeps it, for the money assigned to a category (budgeted, shown as Assigned), hence set_category_budget and get_budget_vs_actual.

YNAB’s references

• YNAB API documentation — endpoints, authentication, rate limit
• OpenAPI specification — the source of the YNAB API coverage page
• We Renamed the Budget Tab to Plan — YNAB’s announcement
• Navigating Multiple Plans in YNAB
• How to Adjust Your Plan Settings

The local copy of transactions

Most tools need the budget’s transactions: to find what is pending, to learn from history, to compare with the bank, to forecast. Downloading them all on every call would be slow and would spend YNAB’s quota. avenir-mcp keeps a copy per budget, in memory, and refreshes it with YNAB’s delta sync:

1. The first load asks for every transaction and keeps YNAB’s server_knowledge, a counter of changes.
2. The next load sends last_knowledge_of_server and receives only what changed since: new, modified and deleted transactions.
3. avenir-mcp merges them into its copy: a changed transaction replaces the old one, a deleted one is removed.

With a budget’s id, the copy is refreshed by delta sync. With last-used, which names whichever budget you last opened in YNAB and may change between two calls, transactions are loaded in full every time — still one request — so two budgets are never mixed. With several budgets, pass the id from list_plans.

The copy lives as long as the server process. Filtered reads — by date or by category — bypass it.

Note

An early version kept only the counter, not the transactions: every load after the first returned only the changes, usually nothing, and suggestions never found any history. A test now checks that an empty delta leaves the full list intact.

YNAB’s rate limit

YNAB allows 200 requests per hour per token, over a rolling window. What each tool costs, on a cold cache, is measured on the demo budget and stated on its reference page:

Cost	Tools
0	any call refused by validation (a malformed month, an empty name…)
1	list_plans, list_accounts, list_category_groups, get_monthly_summary, get_category_balances, get_budget_vs_actual, approve_transactions, a preview of set_category_budget
2	reconcile_account, create_transactions, create_category, update_category, undo_operation
3	find_transactions, list_scheduled_transactions, suggest_categories (a whole page), apply_categories, a preview of split_transaction
4	forecast_balance
1 + N	get_spending_trends over N months

Applying a confirmed write adds its own request (one bulk PATCH for any number of transactions). With a warm cache, reading transactions again costs one small delta request.

When the quota is spent YNAB answers 429 without saying when to come back, so avenir-mcp retries nothing: it returns … YNAB 429: … and sends no request at all for 10 minutes. It also stops by itself at 180 requests in the last hour, leaving the rest to other apps using the same token, and says in how many minutes the next request can leave. Either way, the agent is told to tell you and not to retry before then.

What is never stored

avenir-mcp keeps no copy on disk. The transactions live in memory while the server runs; the journal holds identifiers only; the token stays in the environment and is never logged.