ynab-mcp
An MCP server that exposes the YNAB budgeting API so an LLM can read and manage your budget through natural language.
Read budget data: user info, budgets, accounts, categories, payees, payee GPS locations, months, money movements, transactions, and scheduled transactions (with delta and date/type filters).
Create and edit: accounts, categories and category groups, payee names, budgeted amounts per category-month, and transactions (single, bulk, or split).
Delete: transactions and scheduled transactions; trigger imports from linked banks.
Manage recurring money: create/update/delete scheduled transactions with frequencies from daily to yearly.
Keep card payments honest: audit credit card/line-of-credit payment categories for month-over-month drift, with optional auto-fix.
Run guided workflows: merge or clean up categories, audit budget integrity and account reconciliation, plan a month by rules, suggest categories for uncategorized transactions, and enrich transactions from Apple/Amazon receipts.
Check rate limits:
get_api_usagereports local estimates against the 200 calls/hour YNAB allowance at zero API cost.Ground context without tool calls: resources for a budget summary, accounts, monthly categories, and paged account transactions, plus 6 prompts (monthly review, transaction audit, budget setup, spending analysis, credit card audit, reconcile account).
Extras when configured: Amazon order/receipt matching, tracking-account balance reconciliation (Plaid investments, BTC/ETH/SOL wallets), an AI flag on transactions the server touches, and private budget preferences exposed via tool, resource, and prompts.
Integrates with an Amazon orders service to retrieve Amazon orders and receipts, then match them to YNAB transactions, write product names into memos, and categorize or split transactions based on learned item categories.
Matches Apple receipts to YNAB transactions, writing product names into memos and categorizing or splitting transactions using learned item-to-category mappings.
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 How much do I have left in my Groceries category 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.
ynab-mcp
An MCP (Model Context Protocol) server that exposes the full YNAB API, allowing LLMs to read and manage your budget through natural language. Provides tools for CRUD operations, resources for ambient budget context, and prompts for guided financial workflows.
Requirements
Node.js 20+
Related MCP server: YNAB MCP Server
Run it as a service (Docker)
cp .env.example .env # fill in YNAB_API_TOKEN
docker compose up -dThe server speaks Streamable HTTP
at http://<host>:8000/mcp (also at /), with a health check at /health, and serves both
2026-07-28 and older session-based clients. Point any MCP client at it:
{ "mcpServers": { "ynab": { "type": "http", "url": "http://localhost:8000/mcp" } } }Variable | Default | Meaning |
| (required) | YNAB personal access token |
|
|
|
|
| HTTP port |
| (unset) | An amazon-orders service (see the homelab repo); enables |
| (unset) | Where each tracking account's real balance comes from; enables |
| (unset) | BTCPay Greenfield API for fast, indexed watch-only BTC balances and tracked history; see Tracking balances |
| (unset) | Your own bitcoind (BTC block dates; legacy UTXO scans without BTCPay) and Ethereum RPC |
| (unset), | Read-only Plaid access for investment accounts in |
| (unset: off) | A flag color ( |
|
| Where enrich_transactions remembers item categories; mount a volume |
| (unset) | Optional UTF-8 Markdown budget preferences, loaded at startup; see Budget preferences |
| (any) | Comma-separated hostnames allowed in the |
Running as a long-lived service also keeps the rate-limit accounting and the get_budget
snapshot cache warm across calls. Images: ghcr.io/justmytwospence/ynab-mcp, published for
amd64 and arm64 by pushing a vX.Y.Z tag.
Installation (stdio)
npm install -g ynab-mcpOr install from source:
git clone https://github.com/justmytwospence/ynab-mcp.git
cd ynab-mcp
npm install
npm run build
npm install -g .Configuration
Set your YNAB API token as an environment variable:
export YNAB_API_TOKEN="your-token-here"Generate a token at YNAB > Account Settings > Developer Settings.
Budget preferences
Optionally supply your own Markdown document describing budget preferences. The server remains generic without it: no personal defaults, extra guidance tool, or guidance resource. Preferences describe desired outcomes for requested work; they do not request an audit, authorize changes, or enforce constraints in tool calculations. Explicit current user instructions take precedence over preference defaults; operational safety requirements still apply. Existing workflows still need appropriate parameters and previews.
Keep your actual preference document and its mount configuration in your deployment/configuration repository, version-controlled when its contents are suitable for that repository. Do not commit personal preferences to this application repository; none ship in the package or image. A neutral starting paragraph is:
These are preferences for interpreting requested budget work, not a request to perform changes.
The document applies to all budgets served by this deployment; this is not per-budget or multi-user isolation. Clients with access to the MCP can retrieve the complete document, so treat it as private context and do not include credentials.
For standalone self-hosting, compose.guidance.yaml is an optional example: create your own
private/budget-guidance.md, then enable the override below. That example directory is excluded
from Git and the Docker build context. Deployments managed in a separate repository should
mount their own tracked document directly from their own Compose configuration instead.
This feature requires version 3.1.0 or later.
docker compose -f compose.yaml -f compose.guidance.yaml up -dThe override mounts the document using a file-backed Compose config and sets
YNAB_MCP_GUIDANCE_FILE=/config/budget-guidance.md. Setting an environment variable alone
will not mount a host file. The image runs as node; host file permissions must allow that
user to read the document. Host access controls remain your responsibility, and Compose
configs are not encrypted secret storage.
For a direct Node/stdio process, with the normal YNAB token already configured:
YNAB_MCP_GUIDANCE_FILE=/absolute/path/budget-guidance.md node dist/index.jsRelative paths resolve from the process working directory. The document must be a regular file containing nonempty, valid UTF-8 text, without NUL bytes, at most 32 KiB. Configured missing, unreadable, or invalid files stop startup rather than silently omitting preferences. An unset or blank setting disables the feature. Markdown is read as text: no includes, remote fetching, environment interpolation, or execution.
The server loads one immutable snapshot before starting either transport. Its revision is
sha256: followed by the digest of the exact file bytes. Editing the file does not hot-reload
it. Recreate the container after an edit, then reconnect MCP clients:
docker compose -f compose.yaml -f compose.guidance.yaml up -d --force-recreate ynab-mcpFor direct processes, restart the process and reconnect clients instead.
When configured, the same snapshot is exposed through:
get_budget_guidance: a read-only, zero-HTTP tool with no arguments. Returns the full document and revision through the standard text/structured result envelope.ynab://guidance: a static Markdown resource containing the full document and revision.All six existing prompts: full preference context follows the generic operational guidance and precedes the prompt's task. No additional audit prompt is registered.
Server instructions and
ynab://guide: a short discovery notice, not the document body.
MCP clients differ in resource access, prompt surfacing, and handling server instructions. The retrieval tool is a compatibility path, not a guarantee that clients automatically load or obey preferences. No tool behavior or write authorization changes when this is enabled.
Claude Code
claude mcp add ynab-mcp ynab-mcp -e YNAB_API_TOKEN=your-token-hereClaude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"ynab-mcp": {
"command": "ynab-mcp",
"env": {
"YNAB_API_TOKEN": "your-token-here"
}
}
}
}Tools
55 tools, plus 2 optional Amazon tools when configured and the optional get_budget_guidance tool when budget preferences are configured. Tool amount inputs described in dollars use currency units; raw API/structured financial data uses YNAB milliunits (e.g., $12.34 = 12340). Every tool declares all four behavioral hints. Preview/apply workflows remain writes; annotations do not enforce approval or permissions.
Results retain existing text (including format: "json" JSON-in-text) and add a validated structuredContent envelope: text, endpoint/workflow data, api_usage local estimates, and request_cost with actual HTTP attempts and partial-result warnings. Only the stable envelope has an output schema; domain payloads vary by tool. Mutations invalidate cached snapshots even after a lost response. Text is bounded to 128 KiB and domain data to 256 KiB: explicit warnings flag truncation/omission (data: null); oversized JSON-in-text remains valid with result_omitted: true. Narrow requests rather than applying from partial previews.
AI flag
Set YNAB_MCP_AI_FLAG=purple (any YNAB flag color) and every transaction the server creates
or meaningfully edits gets that flag, so you can see and filter what an AI touched. In YNAB,
name the flag (e.g. "AI") and filter by it; through the server, pass flag: "ai" to any
list_*transactions tool.
Marked: creates, and updates to account, date, amount, payee, category, memo or splits, from any tool or workflow. Not marked: cleared/approved/reconciled changes, bank imports, scheduled transactions.
A flag you set yourself is never replaced, and a
flag_colorthe caller passes wins.Marking an update costs one extra API call per write (a follow-up bulk request for the transactions that came back unflagged); creates carry the flag in the request.
A person's choice is not an AI's: pass
human: truetocreate_transaction(s),update_transaction(s)orenrich_transactionswhen the person decided the change (named the category, picked one of your options). Nothing is marked, and an AI flag already on an edited transaction is cleared (one extra call), since a person has now decided it. Their own flag colors are kept.
Tracking balances
get_tracking_balances (read-only) reads the real balance of each tracking account named in
RECONCILE_MAP and compares it with YNAB's cleared balance. Book the difference with
audit_account_reconciliation (target_balance, apply: true, payee_name: "Market return"),
which reconciles the account the way YNAB's own reconcile does.
[
{"account": "Roth", "plaid": {"link": "vanguard", "masks": ["1234"]}},
{"account": "Crypto", "wallets": [
{"chain": "btc", "address": "zpub...", "btcpay": {"store_id": "tracking-store", "history_since": "2026-11-03"}},
{"chain": "eth", "address": "0x..."},
{"chain": "eth", "address": "0x...", "token": {"contract": "0xA0b8...", "decimals": 6, "coingecko": "usd-coin", "symbol": "USDC"}},
{"chain": "sol", "address": "..."}
]}
]Crypto uses public wallet information only; no seed or private key is needed:
Indexed BTC (recommended): a wallet's
btcpaymapping reads its confirmed balance from BTCPay's existing NBXplorer/Bitcoin Core index. SetBTCPAY_URLand aBTCPAY_API_KEYscoped tobtcpay.store.canviewwalletfor that store. Normal reads never register a wallet, generate an address, scan the UTXO set, or contact explorers. Unavailable, unsynchronized, unauthorized, or malformed results are errors, not zero balances or permission to fall back to another source.Legacy BTC: omit
btcpayto keep the existing direct-node/public-explorer behavior. WithBITCOIN_RPC_URL,BITCOIN_RPC_USERandBITCOIN_RPC_PASSWORD, a synced node runsscantxoutset(receive/change descriptors, range 0-999). This can take minutes on every read; it is not a wallet index. Without a ready node, public explorers are used (extended-key derivation is local, gap limit 20). The legacy balance RPC user needsgetblockchaininfo,scantxoutset.ETH and ERC-20:
ETH_RPC_URL(for example a Helios light client), else a public node.SOL: Solana's public RPC. Prices: CoinGecko.
Set up an indexed BTC wallet
In BTCPay, connect the existing public account key to a dedicated watch-only store wallet. Verify its network, script type, and receive/change addresses against the originating wallet. Never replace a donation wallet with a personal tracking account.
For an existing wallet, use BTCPay's native wallet Rescan once and wait for completion. This discovers current coins through NBXplorer and works with a pruned Core node. Verify the balance and discovery range; a completed scan does not prove complete old history.
Set
history_sinceto the first complete UTC day after initialization. Indexed history is supported from that date; earlier requests fail explicitly. A UTXO scan cannot recover every already-spent transaction. Review an opening reconciliation separately rather than treating missing history as zero or automatically booking it as market return.Issue a store-scoped
btcpay.store.canviewwalletkey, without wallet-management, transaction-creation, signing, broadcast, or administrative permissions. Store the key in environment/secrets, never inRECONCILE_MAP. The API permission also permits a receive-address endpoint that can generate an address; this adapter never calls it. The upstream permission is therefore not literally mutation-free, even though all adapter requests are reads and the watch-only wallet cannot sign.For movement dates, configure Bitcoin RPC with a user restricted to
getblockchaininfo,getblockheader. BTCPay's first-seen timestamps are not confirmation dates; the adapter uses Core's block timestamps to preserve date-based valuation. It reads native net wallet movements, not individual-address scans. On BTCPay 2.4.6, confirmed-only filtered pagination avoids the unfiltered transaction-list skip bug.
Restore NBXplorer's database with BTCPay's state: future tracked history is not necessarily reconstructible from a pruned node. ETH/SOL history remains unsupported. Generic legacy BTC history still uses public explorers.
Each wallet line in get_tracking_balances says where it was read. Nothing here can sign or move funds.
Investment accounts use Plaid's free Trial plan, read-only:
The server can call exactly two Plaid endpoints,
/investments/holdings/getand/accounts/get(enforced insrc/sources/plaid.tsand tested). Plaid has no endpoint that trades or withdraws from an investment account.Links are made with
node dist/plaid-link.js linkin the container. It asks Plaid forinvestmentsonly, then keeps the link only if the institution uses OAuth (Plaid never sees your password), the link consents to nothing beyond investments and identity (Fidelity's links carry identity; the server never requests it), and/auth/get(account and routing numbers) is refused. Otherwise it removes the link.search <name>shows whether an institution links through OAuth before you try.PLAID_TOKENSis a JSON object of link name to access token. Keep it with the YNAB token; errors never include it. Revoke a link at my.plaid.com or at the institution (Fidelity Access), or rotatePLAID_SECRETin the Plaid dashboard to cut off every link at once.
Rate limit awareness
The YNAB API allowance is 200 requests/token/rolling hour. Accounting here is a local estimate, not authoritative remaining quota: other clients using the same access token and previous process lifetimes are invisible. YNAB's own web/mobile sessions are not assumed to use this token. Every actual YNAB HTTP attempt counts, including failed transports, retries, and AI/human flag follow-ups.
get_api_usage/ynab://api-usage: cached/local status, zero HTTP. Includes observation times, reservations, next available slot, last 429/403.4, and cooldown. No remaining/reset headers are invented.windowResetsAtis the next observed call expiry, not an all-at-once reset.allObservedCallsExpireAtassumes no further calls;nextAvailableSlotAtis only a local estimate.Local admission blocks requests at exhaustion, reserves known-cost batch phases, and bounds upstream concurrency to 4, queue to 64, and request timeouts to 45 seconds. Reservations cannot guarantee external quota or atomic writes.
Safe GET/HEAD reads may retry once for 429/500/502, with at most 5 seconds backoff, or after 0.5 seconds when the connection drops (refused, reset, or cut off mid-body; never after a 45-second timeout). A longer
Retry-Afteris exposed as cooldown rather than slept through; absent 429 headers use a labeled local 60-second backoff. Writes and timeouts are never automatically replayed. A transport failure (no complete HTTP response: refused, reset, cut off mid-body, timed out) is reported with the method, endpoint, elapsed time, the network cause, and whether it was a read (safe to retry; says so when the automatic retry failed too) or a write (may have applied), instead of the SDK's generic "The request failed and the interceptors did not return an alternative response". Inspect current state before retrying mutations, especially partial transfers/reconciliation adjustments.Only error 403.4 records a data-limit event, an unquantified limit distinct from hourly quota. Other 403 permission errors are not called data limits.
Automatic local-estimate warnings appear at 50 or fewer remaining, critical below 20, and reached at zero. JSON-in-text results keep warnings inside JSON.
Tool descriptions show baseline costs; retries and flag follow-ups can add calls. Prefer bulk transaction tools to loops. Snapshot reads normally cost one request (delta refresh), an unusable delta adds one full read, and a 503 fallback adds 5 + M + Y requests (budget months and transaction years) after failed attempts. The fallback preflights discovery and history phases, omits schedules/payee locations, and is not guaranteed to fit the current allowance. Check status before costly reads or apply, preview first, and confirm the specific changes before writing.
User
Tool | Description |
| Get authenticated user info |
Budgets
Tool | Description |
| List all budgets with optional account info |
| Refresh a cached export and return a summary/counts/provenance, not the full export; workflows and scoped resources reuse the cache |
| Get date and currency format settings |
Accounts
Tool | Description |
| List all accounts with balances and types |
| Get details for a single account |
| Create a new account |
Categories
Tool | Description |
| List all categories grouped by category group |
| Get details for a single category |
| Create a new category |
| Update a category's name, note, or goal |
| Get a category's budget for a specific month |
| Update budgeted amount for a category in a month |
| Create a new category group |
| Update a category group's name |
Transactions
Tool | Description |
| List transactions with optional filters |
| Get details for a single transaction |
| Create a new transaction |
| Batch create multiple transactions |
| Update an existing transaction, or split a non-split one ( |
| Bulk update multiple transactions |
| Delete a transaction |
| Import from linked financial institutions |
| List transactions for a specific account |
| List transactions for a specific category |
| List transactions for a specific payee |
| List transactions for a specific month |
Scheduled Transactions
Tool | Description |
| List all scheduled/recurring transactions |
| Get details for a scheduled transaction |
| Create a new scheduled transaction |
| Update a scheduled transaction |
| Delete a scheduled transaction |
Payees
Tool | Description |
| List all payees |
| Get details for a single payee |
| Update a payee's name |
| Create a payee |
Payee Locations
Tool | Description |
| List all payee GPS locations |
| Get a single payee location |
| Get all locations for a specific payee |
Months
Tool | Description |
| List all budget months with summaries |
| Get detailed month info with category balances |
Money Movements
Tool | Description |
| List all money movements |
| Get money movements for a specific month |
| List all money movement groups |
| Get money movement groups for a specific month |
Workflows
Tool | Description |
| Merge a source category into a target, moving all transactions and budgeted amounts (1 API call to preview) |
| Clean up a category for deletion: re-categorizes all history to a replacement and zeros budgets, final delete is manual in the YNAB app — API limitation (1 API call to preview) |
| Audit credit card and line-of-credit funding gaps for unexplained month-over-month drift, with optional auto-fix (1 API call) |
| Diagnose an account's reconciliation state (cleared vs. bank balance, unreconciled txn list) with optional close-out |
| Find overspent past category-months, negative Ready to Assign months, uncategorized spending and every card month-end where the payment category differs from what the card owes; plan and optionally apply repairs (from Ready to Assign, else bridged from unused money; a past month whose Ready to Assign is already negative is settled history and blocks nothing unless |
| Set a month's assigned amounts by rules you pass, in order: |
| Suggest categories for uncategorized and unapproved transactions from your history (payee + amount, then payee); bulk-apply the obvious ones (1 API call to suggest) |
| enrich_transactions | Match Apple/Amazon receipts to transactions, write the product names into the memo, categorize or split by remembered item categories (1 API call to plan) |
| list_item_categories | The item -> category mappings learned so far (0 API calls) |
The snapshot workflows normally read one cached export/delta; the costs above are baselines, not fallback caps. audit_budget_integrity, plan_month, suggest_categories and enrich_transactions accept format: "json" for automation. Other workflows retain text plus structured results; list_item_categories reads only local state.
Resources
Resources provide structured budget data that clients can pull into context without a tool call. Template resources use URI parameters (e.g., {budget_id}).
Resource | URI | Description | API Cost |
Usage Guide |
| Discoverable costs/safety guide, all template URIs and prompt names with examples (also usable by clients without templates/list or initialize instructions) | 0 HTTP |
API Usage |
| Local rolling-hour estimates, next slot/cooldown and cached snapshot metadata; includes budget/preview guidance | 0 HTTP |
Budget Summary |
| Snapshot overview with provenance; up to 100 accounts/groups | Snapshot |
Account List |
| Account balances/status; up to 500 rows | Normally 1 |
Monthly Categories |
| Category amounts for one month; up to 500 rows | Normally 1 |
Category Month |
| One category-month with provenance and goal-history caveat | Snapshot |
Account Transactions |
| At most 366 days and 100 rows/page (byte bounds may return fewer), offset up to 10000; | Snapshot |
Snapshot resource reads cost 0 when the cache is younger than 60 seconds; otherwise normal snapshot/delta/fallback costs above apply. Resource text is capped at 64 KiB with an explicit truncation notice. Dates use YYYY-MM-DD, months use the first of the month. Paging/filters bound returned context, not upstream work: YNAB has no export pagination. All resources use the same token/budget scope as tools, never write, and disclose network costs. Listing resources/templates or retrieving prompts performs no HTTP or filesystem writes.
Prompts
Prompts are guided workflow templates; retrieval makes zero HTTP requests and does not execute the suggested actions. Each includes budget checks, batching, explicit history windows, preview/confirmation and no-blind-replay guidance. ynab://guide lists invocation examples and suggested-action costs.
Prompt | Arguments | Description |
|
| Review a budget month: overspent categories, spending variances, underfunded goals, CC mismatches |
|
| Audit transactions for uncategorized, unapproved, duplicates, and unusual amounts |
|
| Guided walkthrough: accounts, categories, targets, scheduled transactions, fund allocation |
|
| Category breakdown, budget vs. actual, top payees, income vs. spending |
|
| Audit CC payment category balances with dry-run-first, confirm-before-apply flow |
|
| Walk through reconciling an account against a bank balance, with missing-transaction triage |
Development
npm run dev # Watch mode with tsx
npm run build # Compile TypeScript
npm test # Offline contract, snapshot, usage and workflow tests (no account calls)
npm start # Run compiled serverLicense
MIT, see LICENSE.
Available Tools
47 toolsaudit_credit_card_paymentsAudit Credit Card PaymentsA
[Variable API calls] [Workflow] Audits credit card payment categories by comparing each card's month-end balance against the payment category's available balance. Recommends exact budgeted amount corrections, accounting for cascading effects across months. Audit costs 3 + C + M API calls (C = credit cards, M = months). Set apply=true to automatically fix mismatches (adds 1 API call per mismatch).
Inputs: budget_id, since_month, account_id, apply.
create_accountCreate AccountB
[1 API call] Create a new account in a budget
Inputs: name (required), type (required), balance (required), budget_id.
create_categoryCreate CategoryB
[1 API call] Create a new category in a budget
Inputs: name (required), category_group_id (required), budget_id, note, +2 more.
create_category_groupCreate Category GroupA
[1 API call] Create a new category group in a budget
Inputs: name (required), budget_id.
create_scheduled_transactionCreate Scheduled TransactionA
[1 API call] Create a new scheduled (recurring) transaction. Date must be in the future (up to 5 years).
Inputs: account_id (required), date (required), amount (required), frequency (required), +6 more.
create_transactionCreate TransactionA
[1 API call] Create a new transaction. Amounts are in dollars (positive for inflows, negative for outflows). For split transactions, set category_id to null and provide subtransactions.
Inputs: account_id (required), date (required), amount (required), budget_id, +8 more.
create_transactionsCreate Multiple TransactionsA
[1 API call, bulk] Create multiple transactions at once. Each transaction needs account_id, date, and amount at minimum.
Inputs: transactions (required), budget_id.
delete_scheduled_transactionDelete Scheduled TransactionBDestructive
[1 API call] Delete a scheduled transaction
Inputs: scheduled_transaction_id (required), budget_id.
delete_transactionDelete TransactionBDestructive
[1 API call] Delete a transaction
Inputs: transaction_id (required), budget_id.
get_accountGet AccountBRead-only
[1 API call] Get details for a single account
Inputs: account_id (required), budget_id.
get_api_usageGet API UsageARead-only
[0 API calls] Check current YNAB API usage against the 200 calls/hour rate limit. Use this before batch operations to ensure you have enough budget.
Inputs: no named parameters.
get_budgetGet BudgetARead-only
[1 API call] Get a single budget's full detail including all entities. Use 'last-used' for the most recently accessed budget.
Inputs: budget_id, last_knowledge_of_server.
get_budget_settingsGet Budget SettingsBRead-only
[1 API call] Get a budget's date and currency format settings
Inputs: budget_id.
get_categoryGet CategoryBRead-only
[1 API call] Get details for a single category
Inputs: category_id (required), budget_id.
get_monthGet Budget MonthARead-only
[1 API call] Get detailed info for a single budget month including all category balances. Use 'current' for the current month.
Inputs: month (required), budget_id.
get_month_categoryGet Month CategoryBRead-only
[1 API call] Get a category's budget details for a specific month
Inputs: month (required), category_id (required), budget_id.
get_month_money_movement_groupsGet Month Money Movement GroupsBRead-only
[1 API call] Get money movement groups for a specific month
Inputs: month (required), budget_id.
get_month_money_movementsGet Month Money MovementsBRead-only
[1 API call] Get money movements for a specific month
Inputs: month (required), budget_id.
get_payeeGet PayeeBRead-only
[1 API call] Get details for a single payee
Inputs: payee_id (required), budget_id.
get_payee_locationGet Payee LocationBRead-only
[1 API call] Get a single payee location by ID
Inputs: payee_location_id (required), budget_id.
get_payee_locations_for_payeeGet Locations for PayeeBRead-only
[1 API call] Get all GPS locations for a specific payee
Inputs: payee_id (required), budget_id.
get_scheduled_transactionGet Scheduled TransactionBRead-only
[1 API call] Get details for a single scheduled transaction
Inputs: scheduled_transaction_id (required), budget_id.
get_transactionGet TransactionBRead-only
[1 API call] Get details for a single transaction
Inputs: transaction_id (required), budget_id.
get_userGet UserBRead-only
[1 API call] Get the authenticated user's information including user ID
Inputs: no named parameters.
import_transactionsImport TransactionsB
[1 API call] Trigger an import of transactions from linked financial institutions
Inputs: budget_id.
list_accountsList AccountsARead-only
[1 API call] List all accounts for a budget including balances and types
Inputs: budget_id, last_knowledge_of_server.
list_account_transactionsList Account TransactionsBRead-only
[1 API call] List transactions for a specific account
Inputs: account_id (required), budget_id, since_date, type, +1 more.
list_budgetsList BudgetsARead-only
[1 API call] List all budgets the user has access to, with optional account info
Inputs: include_accounts.
list_categoriesList CategoriesBRead-only
[1 API call] List all categories grouped by category group for a budget
Inputs: budget_id, last_knowledge_of_server.
list_category_transactionsList Category TransactionsBRead-only
[1 API call] List transactions for a specific category
Inputs: category_id (required), budget_id, since_date, type, +1 more.
list_money_movement_groupsList Money Movement GroupsBRead-only
[1 API call] List all money movement groups for a budget
Inputs: budget_id.
list_money_movementsList Money MovementsBRead-only
[1 API call] List all money movements for a budget (funds moved between categories)
Inputs: budget_id.
list_monthsList Budget MonthsARead-only
[1 API call] List all budget months for a budget, showing income, budgeted, activity, and ready to assign
Inputs: budget_id, last_knowledge_of_server.
list_month_transactionsList Month TransactionsBRead-only
[1 API call] List transactions for a specific month
Inputs: month (required), budget_id, since_date, type, +1 more.
list_payee_locationsList Payee LocationsBRead-only
[1 API call] List all payee GPS locations for a budget
Inputs: budget_id.
list_payeesList PayeesBRead-only
[1 API call] List all payees for a budget
Inputs: budget_id, last_knowledge_of_server.
list_payee_transactionsList Payee TransactionsBRead-only
[1 API call] List transactions for a specific payee
Inputs: payee_id (required), budget_id, since_date, type, +1 more.
list_scheduled_transactionsList Scheduled TransactionsBRead-only
[1 API call] List all scheduled (recurring) transactions for a budget
Inputs: budget_id, last_knowledge_of_server.
list_transactionsList TransactionsARead-only
[1 API call] List transactions for a budget with optional filters. Returns most recent transactions first.
Inputs: budget_id, since_date, type, last_knowledge_of_server.
merge_categoryMerge CategoryADestructive
[Variable API calls] [Workflow] Merges a source category into a target category: re-categorizes all transactions and moves all historical budgeted amounts. Dry run costs 4 + N calls (N = number of budget months). Execution costs additional 1 + 2*M calls (M = months with non-zero budgets). Defaults to dry_run=true to preview changes before executing. After merging, the source category will have zero transactions and zero budgeted amounts across all months - you can then manually hide/delete it in the YNAB app.
Inputs: source_category_id (required), target_category_id (required), budget_id, dry_run.
update_categoryUpdate CategoryB
[1 API call] Update an existing category's name, note, or goal
Inputs: category_id (required), budget_id, name, note, +2 more.
update_category_groupUpdate Category GroupB
[1 API call] Update a category group's name
Inputs: category_group_id (required), name (required), budget_id.
update_month_categoryUpdate Month Category BudgetA
[1 API call] Update the budgeted/assigned amount for a category in a specific month. This is how you allocate money to categories.
Inputs: month (required), category_id (required), budgeted (required), budget_id.
update_payeeUpdate PayeeB
[1 API call] Update a payee's name
Inputs: payee_id (required), name (required), budget_id.
update_scheduled_transactionUpdate Scheduled TransactionB
[1 API call] Update an existing scheduled transaction
Inputs: scheduled_transaction_id (required), account_id (required), date (required), budget_id, +7 more.
update_transactionUpdate TransactionC
[1 API call] Update an existing transaction
Inputs: transaction_id (required), budget_id, account_id, date, +8 more.
update_transactionsBulk Update TransactionsA
[1 API call, bulk] Update multiple transactions at once. Each must include either id or import_id to identify the transaction.
Inputs: transactions (required), budget_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 47 tools
Most tools have distinct purposes targeting specific resources and actions (e.g., get_account vs. list_accounts), but some overlap exists between list_transactions and more specific listing tools like list_account_transactions, which could cause confusion. The audit_credit_card_payments and merge_category workflows are clearly specialized, reducing ambiguity.
Tool names follow a highly consistent verb_noun pattern throughout, such as create_account, get_budget, list_transactions, and update_category. The two workflow tools (audit_credit_card_payments, merge_category) maintain this structure with descriptive nouns, ensuring predictability across all 47 tools.
With 47 tools, the count is excessive for a budgeting server, leading to a heavy and potentially overwhelming interface. While YNAB's API is comprehensive, many tools (e.g., get_payee_location, list_money_movement_groups) could be consolidated or omitted without losing core functionality, making the set feel bloated.
The tool set provides complete CRUD and lifecycle coverage for YNAB's domain, including accounts, categories, transactions, budgets, and payees. It also includes advanced workflows like auditing and merging, along with utility tools for API usage, ensuring no obvious gaps for agent operations.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
The Ramp MCP server enables users to securely connect Ramp with AI assistants like ChatGPT and Claude to query financial data and take actions using natural language. It transforms Ramp's developer API into a SQL interface that LLMs can query, allowing admins to analyze spend trends, identify cost savings, and run complex SQL analyses on comprehensive datasets (transactions, purchase orders, vendors, users), while all users can manage cards, view transactions, request reimbursements, and get expense policy answers.
Related MCP Servers
- 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
- AlicenseCqualityCmaintenanceExposes YNAB API endpoints as MCP tools, allowing AI assistants to manage budgets, accounts, transactions, and more through natural language.41279 PyPI101MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that connects AI assistants to YNAB budgets, enabling natural language queries about finances backed by full API coverage and built-in YNAB methodology knowledge.1MIT