ynab-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ynab-mcp Show my spending summary for last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ynab-mcp
An MCP (Model Context Protocol) server for YNAB (You Need A Budget), so an LLM client such as Claude Desktop can analyze your budget, accounts, categories, and transactions.
Status: early work in progress. All planned tool areas are implemented: read-only budget analysis, category management, transaction management, and account/budget setup. The one thing not yet done is a manual end-to-end pass through Claude Desktop against a real budget (everything else is covered by the automated test suite).
What it can do today
Tool | Description |
| Get the id of the authenticated user for the configured access token. |
| List all budgets accessible to the configured access token. |
| Get an overview of one budget: metadata plus counts of accounts/categories/payees/transactions. Use the dedicated list tools below for the actual data. |
| Get the date format and currency format settings for a budget. |
| List accounts in a budget, with balances in milliunits and each account's |
| Get a single account by id, including loan details (interest rates, minimum payments) where YNAB has them. |
| List category groups and categories, with budgeted/activity/balance figures for the current month. Supports |
| Get a single category by id, including goal figures. |
| List summary figures (income/budgeted/activity/to_be_budgeted) for every month in a budget's history. Supports |
| Get summary figures plus every category's budgeted/activity/balance for one budget month. |
| List all payees in a budget. Supports |
| Get a single payee by id. |
| List upcoming scheduled (future-dated, recurring) transactions. Supports |
| List transactions in a budget, filterable by date range, |
| Summarize spending (outflow) and income (inflow) per category over a date range, computed client-side from transactions. |
| Create a new category group. |
| Rename an existing category group. |
| Create a new category within an existing category group. |
| Update a category's name, note, category group, and/or goal ( |
| Set the budgeted (assigned) amount for a category in a specific month — the "assign money" action. |
| Move assigned money from one category to another (or from/to Ready to Assign) within a month. |
| Create a single transaction, including transfers ( |
| Create multiple transactions in one call. |
| Update a transaction's account, date, amount, payee, category, memo, cleared status, and/or approved status — also covers approving and categorizing a transaction and turning it into a transfer. |
| Update many transactions in a single API request (e.g. categorize and approve a whole month). |
| Destructive. Merge two imported transactions (one per account) into a single transfer and delete the duplicate. Requires |
| Trigger a bank import on all linked (Direct Import) accounts. |
| Reconcile an account against a statement balance: marks cleared transactions as reconciled and books an adjustment for any difference. |
| Destructive. Permanently delete a transaction. Requires |
| Create a new account ( |
| Create a new payee. |
| Rename an existing payee. |
There is intentionally no ynab_delete_category and no ynab_close_account/ynab_update_account: YNAB's public API has no delete endpoint for categories, no hidden field to hide one either, and no update or close endpoint for accounts at all — AccountsApi in the underlying SDK only exposes create/get/list. Once you create an account or category with this server, there's no way to close, hide, or delete it through the API (or any other API client) — you'd need to do that from the YNAB app itself.
Other API limitations worth knowing:
Loan accounts (
mortgage,autoLoan,studentLoan,personalLoan,medicalDebt,otherDebt,lineOfCredit) can't be created through the API — it only accepts the six types above. Interest rates, minimum payments and escrow amounts are read-only too. UseotherLiabilityto track a loan without YNAB's loan features, or create the loan account in the YNAB app.Goal types can't be chosen: YNAB picks
NEED(orMFfor credit card payment categories,DEBTfor loan categories) when a goal is created. The cadence of aNEEDgoal can be set viagoal_frequency, and a "save X by date" goal viagoal_target_date.goal_frequencyand removing a goal withgoal_target: nullare part of the current YNAB API (1.87.0) but not yet of theynabSDK's types, sosrc/ynab/client.tsinjects them into the request body itself.Split transactions can be created, and a non-split transaction can be turned into a split, but the lines of an existing split can't be changed — delete and re-create the transaction instead.
Delta sync: the list tools marked above accept an optional last_knowledge_of_server input and always return a server_knowledge value in their result. Save that value and pass it back in on your next call to that tool to receive only the entities that changed since then, instead of re-fetching the whole collection — useful if you're polling the same budget repeatedly and want to stay well under YNAB's 200-requests/hour rate limit.
Error messages: every tool error includes a short note on whether retrying makes sense — rate-limit (429) and network errors say to back off and retry later, everything else (bad ids, auth failures, validation errors) says retrying the same call won't help and what to check instead.
Related MCP server: ynab-mcp
Setup
Prerequisites
Node.js >= 20
pnpm (this repo pins
pnpm@10.33.0via thepackageManagerfield)A YNAB Personal Access Token (YNAB web app → Account Settings → Developer Settings → New Token)
Install and build
pnpm install
pnpm buildThis produces dist/index.js, an executable Node script (it also has a bin entry, so once published you'll be able to run it via npx ynab-mcp).
Configure Claude Desktop
Add the server to your Claude Desktop MCP config (claude_desktop_config.json):
{
"mcpServers": {
"ynab": {
"command": "node",
"args": ["/absolute/path/to/ynab-mcp/dist/index.js"],
"env": {
"YNAB_ACCESS_TOKEN": "<your personal access token>"
}
}
}
}Restart Claude Desktop and the ynab_* tools should be available.
Environment variables
Variable | Required | Description |
| Yes | Your YNAB Personal Access Token. Grants full read/write access to your entire YNAB account — YNAB does not support scoped tokens, so treat this the same as a password. |
| No | Overrides the YNAB API base URL (defaults to |
Safety
Category and transaction management tools create and modify data in your live budget. Create/update tools are annotated
readOnlyHint: false,destructiveHint: false(data isn't lost, just changed).ynab_delete_transaction(andynab_match_transfer, which deletes the duplicate side of a transfer) are the destructive tools: they're annotateddestructiveHint: true, require an explicitconfirm: truefield in the tool call (calls without it are rejected before any request reaches YNAB), and return the deleted transaction's fields in the result so the call is auditable afterwards. Host-level tool-call approval (e.g. in Claude Desktop) remains the primary line of defense against a bad or malicious tool call — theconfirmfield is defense-in-depth, not a substitute for it.YNAB personal access tokens are not scoped — there's no way to grant this server read-only or budget-limited access. It gets full read/write access to your entire YNAB account, same as the YNAB app itself.
Your access token is read once from the
YNAB_ACCESS_TOKENenvironment variable at startup and is never logged or written to disk by this server.
Development
pnpm dev # watch mode, restarts the server on change
pnpm typecheck # tsc --noEmit
pnpm lint # oxlint
pnpm format # oxfmt
pnpm test # unit + integration tests (vitest)The integration tests (test/integration/server.test.ts) run the real MCP server against the real ynab SDK, with MSW mocking the underlying HTTP calls to api.ynab.com — no live network access or real YNAB account needed to run pnpm test.
pnpm test:live is reserved for opt-in tests against a real YNAB account (gated behind env vars, excluded from pnpm test), but that test suite hasn't been written yet — running it today will just report "no test files found."
See CLAUDE.md for architecture notes.
License
Available Tools
27 toolsynab_assign_budgeted_amountAssign a budgeted amount to a YNAB categoryAIdempotent
Set the budgeted (assigned) amount for a category in a specific month — the "assign money" action. Amount is in milliunits and replaces the existing budgeted amount for that month, it does not add to it.
Inputs: month (required), budgeted (required), budget_id (required), category_id (required).
ynab_create_accountCreate a YNAB accountA
Create a new on-budget account. There is no API-supported way to close/delete an account afterwards — YNAB's public API has no update or close endpoint for accounts, only create and read, so this action can't be undone through this server (or any other API client).
Inputs: name (required), type (required), balance (required), budget_id (required).
ynab_create_categoryCreate a YNAB categoryA
Create a new category within an existing category group.
Inputs: name (required), budget_id (required), category_group_id (required), note.
ynab_create_category_groupCreate a YNAB category groupA
Create a new category group in a budget.
Inputs: name (required), budget_id (required).
ynab_create_payeeCreate a YNAB payeeB
Create a new payee in a budget.
Inputs: name (required), budget_id (required).
ynab_create_transactionCreate a YNAB transactionA
Create a single transaction. Amount is in milliunits: negative = outflow (spending), positive = inflow.
Inputs: date (required), amount (required), budget_id (required), account_id (required), +6 more.
ynab_create_transactions_bulkCreate multiple YNAB transactionsA
Create multiple transactions in a single call. Amounts are in milliunits: negative = outflow (spending), positive = inflow.
Inputs: budget_id (required), transactions (required).
ynab_delete_transactionDelete a YNAB transactionADestructiveIdempotent
Permanently delete a transaction. This cannot be undone via the API. Requires confirm: true.
Inputs: confirm (required), budget_id (required), transaction_id (required).
ynab_get_accountGet a YNAB accountARead-onlyIdempotent
Get a single account by id, with balances in milliunits.
Inputs: budget_id (required), account_id (required).
ynab_get_budgetGet a YNAB budgetARead-onlyIdempotent
Get an overview of one budget: metadata plus counts of accounts/categories/payees/transactions. For the actual account, category, or transaction data, use ynab_list_accounts / ynab_list_categories / ynab_list_transactions instead — this tool intentionally does not return the full embedded export (which can be very large for budgets with long history).
Inputs: budget_id (required).
ynab_get_budget_settingsGet YNAB budget settingsARead-onlyIdempotent
Get the date format and currency format settings for a budget.
Inputs: budget_id (required).
ynab_get_categoryGet a YNAB categoryARead-onlyIdempotent
Get a single category by id, including budgeted/activity/balance and goal figures (in milliunits) for the current month.
Inputs: budget_id (required), category_id (required).
ynab_get_monthGet a YNAB budget monthARead-onlyIdempotent
Get summary figures for one budget month plus every category's budgeted/activity/balance for that month (all in milliunits).
Inputs: month (required), budget_id (required).
ynab_get_payeeGet a YNAB payeeBRead-onlyIdempotent
Get a single payee by id.
Inputs: payee_id (required), budget_id (required).
ynab_get_spending_summaryGet YNAB spending summary by categoryARead-onlyIdempotent
Summarize spending (outflow) and income (inflow) per category over a date range, computed client-side from transactions (YNAB has no single endpoint for this). Defaults to the last 30 days if since_date is not given. Narrow the date range for large or long-lived budgets, both to keep the response small and to avoid burning YNAB's 200-requests/hour rate limit.
Inputs: budget_id (required), since_date, until_date.
ynab_get_userGet YNAB userARead-onlyIdempotent
Get the id of the authenticated user for the configured access token.
Inputs: no named parameters.
ynab_list_accountsList YNAB accountsARead-onlyIdempotent
List all accounts (checking, savings, credit card, etc.) in a budget, with balances in milliunits.
Inputs: budget_id (required), last_knowledge_of_server.
ynab_list_budgetsList YNAB budgetsARead-onlyIdempotent
List all budgets accessible to the configured YNAB access token.
Inputs: no named parameters.
ynab_list_categoriesList YNAB categoriesARead-onlyIdempotent
List all category groups and categories in a budget, with budgeted/activity/balance figures (in milliunits) for the current month.
Inputs: budget_id (required), last_knowledge_of_server.
ynab_list_monthsList YNAB budget monthsARead-onlyIdempotent
List summary figures (income/budgeted/activity/to_be_budgeted, in milliunits) for every month in a budget's history.
Inputs: budget_id (required), last_knowledge_of_server.
ynab_list_payeesList YNAB payeesBRead-onlyIdempotent
List all payees in a budget.
Inputs: budget_id (required), last_knowledge_of_server.
ynab_list_scheduled_transactionsList YNAB scheduled transactionsARead-onlyIdempotent
List all upcoming scheduled (future-dated, recurring) transactions in a budget.
Inputs: budget_id (required), last_knowledge_of_server.
ynab_list_transactionsList YNAB transactionsARead-onlyIdempotent
List transactions in a budget. Defaults to the last 30 days if since_date is not given, and returns at most 200 transactions per call (most recent first) with has_more indicating whether more exist for the window. Note: the YNAB API has no result-count limit of its own, so this tool always fetches every transaction in the requested date range before applying the 200-result cap — narrow the date range for large or long-lived budgets rather than requesting everything at once, both to keep the response small and to avoid burning YNAB's 200-requests/hour rate limit on an oversized fetch. For repeated polling of the same budget, prefer last_knowledge_of_server over re-fetching the full date range each time.
Inputs: budget_id (required), since_date, until_date, last_knowledge_of_server.
ynab_update_categoryUpdate a YNAB categoryAIdempotent
Update a category's name, note, and/or which category group it belongs to. Only the fields provided are changed. To change the budgeted (assigned) amount for a specific month, use ynab_assign_budgeted_amount instead.
Inputs: budget_id (required), category_id (required), name, note, +1 more.
ynab_update_category_groupUpdate a YNAB category groupBIdempotent
Rename an existing category group.
Inputs: name (required), budget_id (required), category_group_id (required).
ynab_update_payeeUpdate a YNAB payeeBIdempotent
Rename an existing payee.
Inputs: name (required), payee_id (required), budget_id (required).
ynab_update_transactionUpdate a YNAB transactionBIdempotent
Update a transaction's account, date, amount, payee, category, memo, cleared status, and/or approved status. Only the fields provided are changed — this single tool covers approving a transaction, categorizing it, editing its amount, etc.
Inputs: budget_id (required), transaction_id (required), date, memo, +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Each tool targets a distinct resource or action (e.g., create vs list, single vs bulk, budget vs month). Descriptions clearly differentiate overlapping pairs like get/list and single/bulk transactions.
All tools follow the verb_noun pattern consistently with snake_case and the ynab_ prefix. The few exceptions like ynab_assign_budgeted_amount still adhere to the same pattern.
27 tools cover many YNAB entities and operations, but the count is slightly high. Some operations could be combined (e.g., single/bulk create transaction) without loss of clarity.
Core CRUD operations are present for transactions, categories, payees, and accounts (though account update/delete are missing). Gaps exist for scheduled transaction management and goal-related actions, limiting full lifecycle coverage.
Maintenance
Related MCP Connectors
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Query your real net worth, spending, transactions, budgets and portfolio from any MCP client.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server that allows users to interact with YNAB data, enabling access to account balances, transactions, and the creation of new transactions through the Model Context Protocol.86MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server for interacting with YNAB (You Need A Budget). Provides tools for accessing budget data through MCP-enabled clients like Claude Desktop.4MIT
- FlicenseAqualityBmaintenanceAn MCP server that provides Large Language Models with access to YNAB (You Need A Budget) budgets, allowing them to fetch budget data including accounts, categories, and category groups.326-
- AlicenseAqualityDmaintenanceA minimal and auditable MCP server that enables local AI assistants to read and manage YNAB budget data. It supports operations like listing accounts, tracking transactions, and moving money between categories while maintaining user privacy.9MIT