arcade-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., "@arcade-ynab-mcp show me my budget for this 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.
arcade-ynab-mcp
An MCP server for YNAB, built with
arcade-mcp, hosted on Arcade Cloud via
arcade deploy, and used through Arcade MCP Gateways.
Each user connects their own YNAB account through OAuth 2.0 the first time they call a tool. The server holds no secrets. See docs/SPEC.md for the full design.
Tools
Phase 1 (read-only):
Tool | What it does |
| The authenticated YNAB user |
| The user's plans (budgets) |
| A plan's currency and date formats |
| Ready to Assign, age of money, and every category's amounts for a month |
| Monthly summaries, newest first |
| Accounts and balances |
| Categories, amounts and goals |
| Payees, optionally filtered by name |
| Transactions by date, account, category or payee |
| Upcoming and recurring transactions |
| Money moved between categories |
Phase 2 (writes):
Tool | What it does |
| Add a purchase, income, transfer or split |
| Approve, recategorize, flag or edit up to 100 transactions at once |
| Delete one transaction (destructive) |
| Import new transactions from linked accounts |
| Set a category's assigned amount for a month |
| Move money between categories or Ready to Assign |
| Create or edit categories and their targets |
| Create or rename category groups |
| Create or rename payees |
| Create an unlinked account |
| Manage scheduled transactions |
Phase 3 (summaries, read-only):
Tool | What it does |
| Unapproved transactions with suggested categories |
| Overspent categories and where to cover them from |
| Spending by category, category group or payee for a date range |
| Projected balances from scheduled transactions |
| Underfunded targets and what it takes to fund them |
Every tool is tagged read-only or write (and delete tools as destructive), so a gateway can expose only the read tools. The tags are descriptive, not an approval mechanism; see docs/GATEWAYS.md.
Amounts are in currency units (not YNAB milliunits). Every tool defaults to the user's most recently used plan.
Related MCP server: YNAB MCP Server
Setup
One-time setup of the YNAB OAuth app and the Arcade OAuth provider (ID ynab) is
described in docs/SPEC.md.
Development
uv tool install arcade-mcp # Arcade CLI
uv sync --extra dev # project and dev dependencies
uv run pytest # unit tests (YNAB is mocked; no network)
uv run ruff check . && uv run ruff format --check . && uv run mypy srcTool-selection evals (need an LLM API key; they don't call YNAB):
ANTHROPIC_API_KEY=... uv run arcade evals evals/ -p anthropicTo try the tools against your own YNAB account locally, log in with arcade login
(the OAuth flow runs through your Arcade project), then:
uv run src/arcade_ynab/server.py # stdio
uv run src/arcade_ynab/server.py http # streamable HTTP on :8000Deploy
arcade login
arcade deploy -e src/arcade_ynab/server.pyThen create gateways in the Arcade dashboard: a read gateway for everyday use and, only if you need writes, a separate write gateway with approval required in the client. The tool lists and verification steps are in docs/GATEWAYS.md.
Security
Never commit tokens or personal budget data. Tests use invented data only. YNAB tokens are held by Arcade and injected per request; they are never exposed to the model.
The server uses per-user OAuth only: it reads no secrets or environment variables, so a YNAB personal access token stored as an Arcade secret isn't used. To check a deployment matches this repository and its gateways are private, follow docs/DEPLOYMENT.md.
License
Available Tools
35 toolsYnab_AssignToCategoryAssignToCategoryAIdempotent
Set how much is assigned to a category for a month. The difference comes from, or goes back to, Ready to Assign.
Inputs: amount (required), category_id (required), month, plan_id. Returns: object
Ynab_CreateAccountCreateAccountA
Create an unlinked account with a starting balance. Checking, savings, cash and credit card accounts are on budget; other assets and liabilities are tracking accounts.
Inputs: name (required), balance (required), account_type (required), plan_id. Returns: object
Ynab_CreateCategoryCreateCategoryC
Create a category in a category group, optionally with a target (goal).
Inputs: name (required), category_group_id (required), note, plan_id, +4 more. Returns: object
Ynab_CreateCategoryGroupCreateCategoryGroupC
Create a category group.
Inputs: name (required), plan_id. Returns: object
Ynab_CreatePayeeCreatePayeeA
Create a payee. (CreateTransaction can also create a payee from payee_name.)
Inputs: name (required), plan_id. Returns: object
Ynab_CreateScheduledTransactionCreateScheduledTransactionC
Schedule an upcoming or recurring transaction (bill, paycheck, transfer).
Inputs: date (required), amount (required), frequency (required), account_id (required), +7 more. Returns: object
Ynab_CreateTransactionCreateTransactionB
Create a transaction: a purchase, income, a transfer between accounts, or a split.
Inputs: date (required), amount (required), account_id (required), memo, +9 more. Returns: object
Ynab_DeleteScheduledTransactionDeleteScheduledTransactionADestructiveIdempotent
Permanently delete a scheduled transaction. Only call this when the user has clearly asked to delete this specific scheduled transaction.
Inputs: scheduled_transaction_id (required), plan_id. Returns: object
Ynab_DeleteTransactionDeleteTransactionADestructiveIdempotent
Permanently delete one transaction. Only call this when the user has clearly asked to delete this specific transaction.
Inputs: transaction_id (required), plan_id. Returns: object
Ynab_FindOverspendingFindOverspendingARead-onlyIdempotent
Find overspent categories (negative available) in a month and suggest where to cover them from: Ready to Assign first, then the categories with the most money available that aren't saving toward an underfunded target. Use MoveMoney to cover after the user picks.
Inputs: month, plan_id, max_candidates. Returns: object
Ynab_ForecastCashFlowForecastCashFlowARead-onlyIdempotent
Project account balances over the next N days from current balances and scheduled transactions (bills, paychecks, transfers). Reports each account's ending balance and its lowest point, to spot upcoming shortfalls. Doesn't include unscheduled spending.
Inputs: days, plan_id, account_id. Returns: object
Ynab_GetAccountGetAccountBRead-onlyIdempotent
Get a single account by ID.
Inputs: account_id (required), plan_id. Returns: object
Ynab_GetCategoryGetCategoryARead-onlyIdempotent
Get a single category's amounts and goal progress for a given month.
Inputs: category_id (required), month, plan_id. Returns: object
Ynab_GetMonthGetMonthARead-onlyIdempotent
Get one plan month: Ready to Assign, age of money, income, total assigned and activity, plus every category's assigned, activity and available amounts and goal progress.
Month totals cover all categories. When hidden categories are left out of the list, their combined amounts are in omitted_hidden_categories. Categories marked internal are YNAB system categories (e.g. Inflow: Ready to Assign), not budget lines.
This is the best single call for "how is my budget doing this month?".
Inputs: month, plan_id, include_hidden. Returns: object
Ynab_GetPlanSettingsGetPlanSettingsBRead-onlyIdempotent
Get a plan's currency and date format settings.
Inputs: plan_id. Returns: object
Ynab_GetTransactionGetTransactionBRead-onlyIdempotent
Get a single transaction by ID, including its subtransactions if it is a split.
Inputs: transaction_id (required), plan_id. Returns: object
Ynab_GetUserGetUserARead-onlyIdempotent
Get the YNAB user the current authorization belongs to.
Inputs: no named parameters. Returns: object
Ynab_ImportTransactionsImportTransactionsA
Ask YNAB to import new transactions from the plan's linked (direct import) accounts, like pressing "Import" in the app. Imported transactions arrive unapproved.
Inputs: plan_id. Returns: object
Ynab_ListAccountsListAccountsBRead-onlyIdempotent
List a plan's accounts with their type, whether they're on budget (or tracking only), and their working, cleared and uncleared balances.
Inputs: plan_id, include_closed. Returns: object
Ynab_ListCategoriesListCategoriesARead-onlyIdempotent
List a plan's category groups and categories, with each category's assigned, activity and available amounts for the current month and its goal, if any.
Use GetMonth for amounts in a different month.
Inputs: plan_id, include_hidden. Returns: object
Ynab_ListMoneyMovementsListMoneyMovementsARead-onlyIdempotent
List money moved between categories, or between a category and Ready to Assign, newest first. Movements made together in one action share a money_movement_group_id.
A missing from_category_id means the money came from Ready to Assign; a missing to_category_id means it went to Ready to Assign. Use ListCategories to resolve IDs.
Inputs: limit, month, plan_id. Returns: object
Ynab_ListMonthsListMonthsARead-onlyIdempotent
List monthly summaries for a plan (Ready to Assign, income, assigned, activity, age of money), newest first. Use GetMonth for category detail in a single month.
Inputs: limit, plan_id. Returns: object
Ynab_ListPayeesListPayeesARead-onlyIdempotent
List a plan's payees, sorted by name. Transfer payees (which represent transfers to another account) include the transfer_account_id.
Inputs: limit, plan_id, name_contains. Returns: object
Ynab_ListPlansListPlansBRead-onlyIdempotent
List the user's YNAB plans (budgets), most recently modified first.
Inputs: include_accounts. Returns: object
Ynab_ListScheduledTransactionsListScheduledTransactionsARead-onlyIdempotent
List upcoming and recurring scheduled transactions, soonest first, with their frequency and next date. Amounts are negative for outflows, positive for inflows.
Inputs: limit, plan_id. Returns: object
Ynab_ListTransactionsListTransactionsARead-onlyIdempotent
List transactions, newest first, optionally filtered by date range and by ONE of account, category or payee.
Amounts are in currency units: negative is an outflow, positive is an inflow. Split transactions include their subtransactions. When filtering by category or payee, split lines are returned as their own rows with type 'subtransaction'.
Inputs: limit, plan_id, payee_id, account_id, +4 more. Returns: object
Ynab_MoveMoneyMoveMoneyA
Move money between two categories, or between a category and Ready to Assign, by adjusting their assigned amounts for the month. Running it twice moves the money twice.
The source must have at least the amount available. YNAB has no single "move" call, so this updates the source first and then the destination. If the second step fails, the money is left in Ready to Assign and the error says so.
Inputs: amount (required), month, plan_id, to_category_id, +1 more. Returns: object
Ynab_ReviewGoalsReviewGoalsARead-onlyIdempotent
Review category targets (goals) for a month: which are underfunded and by how much, how many are on track, and whether Ready to Assign can cover the shortfall. Use AssignToCategory or MoveMoney to fund them after the user confirms.
Inputs: month, plan_id. Returns: object
Ynab_ReviewUnapprovedReviewUnapprovedARead-onlyIdempotent
List transactions waiting for approval, each with a suggested category based on how the same payee was categorized recently. Use UpdateTransactions to approve or recategorize them after the user confirms.
Inputs: limit, plan_id, since_date, history_days. Returns: object
Ynab_SummarizeSpendingSummarizeSpendingARead-onlyIdempotent
Summarize spending over a date range, grouped by category, category group or payee.
Counts budget-account transactions only. Transfers between accounts and income (inflows to Ready to Assign) are excluded; refunds reduce spending in their category. Spending is reported as a positive number.
Inputs: since_date (required), limit, plan_id, group_by, +1 more. Returns: object
Ynab_UpdateCategoryUpdateCategoryAIdempotent
Rename a category, change its note or group, or set or remove its target (goal). Only the fields you pass change. (YNAB's API can't hide or unhide categories.)
Inputs: category_id (required), name, note, plan_id, +6 more. Returns: object
Ynab_UpdateCategoryGroupUpdateCategoryGroupBIdempotent
Rename a category group.
Inputs: name (required), category_group_id (required), plan_id. Returns: object
Ynab_UpdatePayeeUpdatePayeeBIdempotent
Rename a payee. The new name shows on all of its transactions.
Inputs: name (required), payee_id (required), plan_id. Returns: object
Ynab_UpdateScheduledTransactionUpdateScheduledTransactionAIdempotent
Change a scheduled transaction. Only the fields you pass change.
Inputs: scheduled_transaction_id (required), date, memo, amount, +8 more. Returns: object
Ynab_UpdateTransactionsUpdateTransactionsAIdempotent
Apply the same changes to one or more transactions in a single request, e.g. approve a batch, recategorize, mark cleared, flag, or fix a memo. Only the fields you pass change.
Inputs: transaction_ids (required), date, memo, amount, +7 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 35 tools
Tools mostly target distinct resources and actions, with clear list/get/create/update/delete boundaries. Minor overlap exists between AssignToCategory and MoveMoney, and between FindOverspending and ReviewGoals, but descriptions clarify the distinction.
Every tool uses the same Ynab_ prefix followed by PascalCase verb-object or verb-phrase naming. The pattern is predictable and consistent across all 35 tools.
35 tools is heavy for an MCP server, exceeding the 3-15 well-scoped range by a wide margin. While YNAB is a broad domain, the surface likely creates choice overload and could be consolidated.
The tool set covers YNAB's core lifecycle for transactions, scheduled transactions, accounts, categories, category groups, payees, months, plans, money movements, goals, approvals, spending summaries, forecasting, imports, user and settings. Missing singular getters are workarounds via list operations, and unsupported deletes align with API limits.
Maintenance
Related MCP Connectors
Ask your AI about your own accounts, debts, budgets and goals. OAuth sign-in, read-only by default.
Read your accounts, budgets and net worth, and draft changes you confirm.
Read-only personal finance for AI agents: budgets, receipts, net worth, bills. OAuth 2.1.
Personal finance by conversation: expenses, receipts, statement import, budgets, net worth.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables interaction with You Need A Budget (YNAB) through their API, allowing users to manage budgets, accounts, categories, transactions, payees, and scheduled transactions through natural language.1223 npm2GPL 3.0
- AlicenseBqualityAmaintenanceEnables AI assistants to interact with YNAB budgets, performing read-only queries by default and optional write operations like creating transactions and managing categories through natural language.45439 npm48MIT
- AlicenseAqualityCmaintenanceEnables reading and writing YNAB budget data, such as listing budgets, accounts, categories, transactions, and creating or updating transactions, through natural language commands.8MIT
- AlicenseAqualityBmaintenanceLets an AI agent read a YNAB budget and ask plain-language questions about it — where money went, what still needs a category, whether an account matches the bank, and when money would run out. Changes such as categorising, splitting or budgeting are read-only by default, and every write is previewed, explicitly confirmed, and undoable.19134 PyPI6MIT