Data and sync
Amounts
Section titled “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 plan’s own currency; spending is negative, money in positive.
Talking to YNAB
Section titled “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
Section titled “Plans, formerly budgets”YNAB’s API changelog records that v1.79.0 (2026-03-05)
renamed /budgets to /plans: 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
Section titled “YNAB’s references”- YNAB API documentation — endpoints, authentication, rate limit
- OpenAPI specification — the source of the YNAB API coverage page
- YNAB API changelog — v1.79.0 (2026-03-05),
/budgetsrenamed to/plans - Navigating Multiple Plans in YNAB
- How to Adjust Your Plan Settings
The local copy of transactions
Section titled “The local copy of transactions”Most tools need the plan’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 plan, in memory, and refreshes it with YNAB’s delta sync:
- The first load asks for every transaction and keeps YNAB’s
server_knowledge, a counter of changes. - The next load sends
last_knowledge_of_serverand receives only what changed since: new, modified and deleted transactions. - avenir-mcp merges them into its copy: a changed transaction replaces the old one, a deleted one is removed.
With a plan’s id, the copy is refreshed by delta sync. With last-used, which
names whichever plan you last opened in YNAB and may change between two calls,
transactions are loaded in full every time — still one request — so two plans are
never mixed. With several plans, pass the id from list_plans.
The copy lives as long as the server process. Filtered reads — by date or by category — bypass it.
YNAB’s rate limit
Section titled “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 plan 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_age_of_money, get_category_balances, get_budget_vs_actual, get_underfunded_targets, get_debt_payoff_plan, approve_transactions, a preview of set_category_budget, a preview of move_money, a preview of flag_transactions, a preview of set_category_target |
| 2 | get_net_worth_trend, get_runway, get_debt_payoff_plan without monthly_budget when a minimum payment is missing, reconcile_account, create_transactions, create_category, update_category, list_payees, a preview of rename_payee, undo_operation |
| 3 | get_runway with essential_groups, get_savings_rate, find_transactions, find_recurring_charges, 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, and that answer is never retried:
avenir-mcp returns … YNAB 429: … and sends no request at all for 10 minutes, or for the
number of seconds YNAB’s Retry-After header asks for when the answer carries one (held
between 1 minute and 1 hour).
avenir-mcp 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.
When YNAB does not answer
Section titled “When YNAB does not answer”A read that fails on the way out — a timeout, a connection refused, a 502, a 503 or a
504 — is sent again, three times in all, with a short wait that doubles in between.
Repeating a read changes nothing, so this costs you only requests, and each try counts
against the 180 of the hour.
A write is different. Once a POST, a PATCH or a DELETE has left, avenir-mcp never
sends it again: YNAB may have applied it and answered into a connection that was already
gone, and a second copy would create a second transaction or a second change. The only
failure that does send a write again is one that proves it never left, such as a
connection that was refused.
So a write whose answer never came back ends in an answer that says exactly that: the
change may or may not be applied, and the agent is told to look with find_transactions
or get_category_balances rather than repeat it. A read that never got through says
instead that nothing was changed and can be asked for again in a few minutes.
What is never stored
Section titled “What is never stored”avenir-mcp keeps no copy on disk. The transactions live in memory while the server runs; the journal holds identifiers, the amounts a budget change or a move assigned, the target to restore and a renamed payee’s two names; the token stays in the environment and is never logged.
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