Skip to main content
Glama
arcade-ynab-mcp

arcade-ynab-mcp

by laughnan

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

Ynab.GetUser

The authenticated YNAB user

Ynab.ListPlans

The user's plans (budgets)

Ynab.GetPlanSettings

A plan's currency and date formats

Ynab.GetMonth

Ready to Assign, age of money, and every category's amounts for a month

Ynab.ListMonths

Monthly summaries, newest first

Ynab.ListAccounts / Ynab.GetAccount

Accounts and balances

Ynab.ListCategories / Ynab.GetCategory

Categories, amounts and goals

Ynab.ListPayees

Payees, optionally filtered by name

Ynab.ListTransactions / Ynab.GetTransaction

Transactions by date, account, category or payee

Ynab.ListScheduledTransactions

Upcoming and recurring transactions

Ynab.ListMoneyMovements

Money moved between categories

Phase 2 (writes):

Tool

What it does

Ynab.CreateTransaction

Add a purchase, income, transfer or split

Ynab.UpdateTransactions

Approve, recategorize, flag or edit up to 100 transactions at once

Ynab.DeleteTransaction

Delete one transaction (destructive)

Ynab.ImportTransactions

Import new transactions from linked accounts

Ynab.AssignToCategory

Set a category's assigned amount for a month

Ynab.MoveMoney

Move money between categories or Ready to Assign

Ynab.CreateCategory / Ynab.UpdateCategory

Create or edit categories and their targets

Ynab.CreateCategoryGroup / Ynab.UpdateCategoryGroup

Create or rename category groups

Ynab.CreatePayee / Ynab.UpdatePayee

Create or rename payees

Ynab.CreateAccount

Create an unlinked account

Ynab.CreateScheduledTransaction / Ynab.UpdateScheduledTransaction / Ynab.DeleteScheduledTransaction

Manage scheduled transactions

Phase 3 (summaries, read-only):

Tool

What it does

Ynab.ReviewUnapproved

Unapproved transactions with suggested categories

Ynab.FindOverspending

Overspent categories and where to cover them from

Ynab.SummarizeSpending

Spending by category, category group or payee for a date range

Ynab.ForecastCashFlow

Projected balances from scheduled transactions

Ynab.ReviewGoals

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 src

Tool-selection evals (need an LLM API key; they don't call YNAB):

ANTHROPIC_API_KEY=... uv run arcade evals evals/ -p anthropic

To 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 :8000

Deploy

arcade login
arcade deploy -e src/arcade_ynab/server.py

Then 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

MIT

Available Tools

35 tools
Ynab_AssignToCategoryAssignToCategoryA
Idempotent

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_DeleteScheduledTransactionDeleteScheduledTransactionA
DestructiveIdempotent

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_DeleteTransactionDeleteTransactionA
DestructiveIdempotent

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_FindOverspendingFindOverspendingA
Read-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_ForecastCashFlowForecastCashFlowA
Read-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_GetAccountGetAccountB
Read-onlyIdempotent

Get a single account by ID.

Inputs: account_id (required), plan_id. Returns: object

Ynab_GetCategoryGetCategoryA
Read-onlyIdempotent

Get a single category's amounts and goal progress for a given month.

Inputs: category_id (required), month, plan_id. Returns: object

Ynab_GetMonthGetMonthA
Read-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_GetPlanSettingsGetPlanSettingsB
Read-onlyIdempotent

Get a plan's currency and date format settings.

Inputs: plan_id. Returns: object

Ynab_GetTransactionGetTransactionB
Read-onlyIdempotent

Get a single transaction by ID, including its subtransactions if it is a split.

Inputs: transaction_id (required), plan_id. Returns: object

Ynab_GetUserGetUserA
Read-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_ListAccountsListAccountsB
Read-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_ListCategoriesListCategoriesA
Read-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_ListMoneyMovementsListMoneyMovementsA
Read-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_ListMonthsListMonthsA
Read-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_ListPayeesListPayeesA
Read-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_ListPlansListPlansB
Read-onlyIdempotent

List the user's YNAB plans (budgets), most recently modified first.

Inputs: include_accounts. Returns: object

Ynab_ListScheduledTransactionsListScheduledTransactionsA
Read-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_ListTransactionsListTransactionsA
Read-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_ReviewGoalsReviewGoalsA
Read-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_ReviewUnapprovedReviewUnapprovedA
Read-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_SummarizeSpendingSummarizeSpendingA
Read-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_UpdateCategoryUpdateCategoryA
Idempotent

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_UpdateCategoryGroupUpdateCategoryGroupB
Idempotent

Rename a category group.

Inputs: name (required), category_group_id (required), plan_id. Returns: object

Ynab_UpdatePayeeUpdatePayeeB
Idempotent

Rename a payee. The new name shows on all of its transactions.

Inputs: name (required), payee_id (required), plan_id. Returns: object

Ynab_UpdateScheduledTransactionUpdateScheduledTransactionA
Idempotent

Change a scheduled transaction. Only the fields you pass change.

Inputs: scheduled_transaction_id (required), date, memo, amount, +8 more. Returns: object

Ynab_UpdateTransactionsUpdateTransactionsA
Idempotent

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

    A3.6/5.0

    Scored across 35 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      12
      23 npm
      2
      GPL 3.0
    • A
      license
      B
      quality
      A
      maintenance
      Enables 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.
      45
      439 npm
      48
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables reading and writing YNAB budget data, such as listing budgets, accounts, categories, transactions, and creating or updating transactions, through natural language commands.
      8
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Lets 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.
      19
      134 PyPI
      6
      MIT