Skip to main content
Glama
ynab-mcp

ynab-mcp

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

Related MCP server: YNAB MCP Server

Run it as a service (Docker)

cp .env.example .env   # fill in YNAB_API_TOKEN
docker compose up -d

The 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

YNAB_API_TOKEN

(required)

YNAB personal access token

MCP_TRANSPORT

stdio (http in the image)

stdio or http

PORT

8000

HTTP port

AMAZON_ORDERS_URL, AMAZON_ORDERS_TOKEN

(unset)

An amazon-orders service (see the homelab repo); enables amazon_order and amazon_receipts

RECONCILE_MAP

(unset)

Where each tracking account's real balance comes from; enables get_tracking_balances. See Tracking balances

BTCPAY_URL, BTCPAY_API_KEY

(unset)

BTCPay Greenfield API for fast, indexed watch-only BTC balances and tracked history; see Tracking balances

BITCOIN_RPC_URL, BITCOIN_RPC_USER, BITCOIN_RPC_PASSWORD, ETH_RPC_URL

(unset)

Your own bitcoind (BTC block dates; legacy UTXO scans without BTCPay) and Ethereum RPC

PLAID_CLIENT_ID, PLAID_SECRET, PLAID_TOKENS, PLAID_ENV

(unset), production

Read-only Plaid access for investment accounts in RECONCILE_MAP

YNAB_MCP_AI_FLAG

(unset: off)

A flag color (purple, ...) put on every transaction this server creates or edits; see "AI flag"

YNAB_MCP_STATE_DIR

./state (/data in the image)

Where enrich_transactions remembers item categories; mount a volume

YNAB_MCP_GUIDANCE_FILE

(unset)

Optional UTF-8 Markdown budget preferences, loaded at startup; see Budget preferences

MCP_ALLOWED_HOSTS

(any)

Comma-separated hostnames allowed in the Host header (set it behind a reverse proxy)

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-mcp

Or 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 -d

The 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.js

Relative 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-mcp

For 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-here

Claude 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_color the 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: true to create_transaction(s), update_transaction(s) or enrich_transactions when 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 btcpay mapping reads its confirmed balance from BTCPay's existing NBXplorer/Bitcoin Core index. Set BTCPAY_URL and a BTCPAY_API_KEY scoped to btcpay.store.canviewwallet for 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 btcpay to keep the existing direct-node/public-explorer behavior. With BITCOIN_RPC_URL, BITCOIN_RPC_USER and BITCOIN_RPC_PASSWORD, a synced node runs scantxoutset (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 needs getblockchaininfo,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

  1. 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.

  2. 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.

  3. Set history_since to 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.

  4. Issue a store-scoped btcpay.store.canviewwallet key, without wallet-management, transaction-creation, signing, broadcast, or administrative permissions. Store the key in environment/secrets, never in RECONCILE_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.

  5. 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/get and /accounts/get (enforced in src/sources/plaid.ts and tested). Plaid has no endpoint that trades or withdraws from an investment account.

  • Links are made with node dist/plaid-link.js link in the container. It asks Plaid for investments only, 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_TOKENS is 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 rotate PLAID_SECRET in 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.

  • windowResetsAt is the next observed call expiry, not an all-at-once reset. allObservedCallsExpireAt assumes no further calls; nextAvailableSlotAt is 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-After is 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_user

Get authenticated user info

Budgets

Tool

Description

list_budgets

List all budgets with optional account info

get_budget

Refresh a cached export and return a summary/counts/provenance, not the full export; workflows and scoped resources reuse the cache

get_budget_settings

Get date and currency format settings

Accounts

Tool

Description

list_accounts

List all accounts with balances and types

get_account

Get details for a single account

create_account

Create a new account

Categories

Tool

Description

list_categories

List all categories grouped by category group

get_category

Get details for a single category

create_category

Create a new category

update_category

Update a category's name, note, or goal

get_month_category

Get a category's budget for a specific month

update_month_category

Update budgeted amount for a category in a month

create_category_group

Create a new category group

update_category_group

Update a category group's name

Transactions

Tool

Description

list_transactions

List transactions with optional filters

get_transaction

Get details for a single transaction

create_transaction

Create a new transaction

create_transactions

Batch create multiple transactions

update_transaction

Update an existing transaction, or split a non-split one (subtransactions)

update_transactions

Bulk update multiple transactions

delete_transaction

Delete a transaction

import_transactions

Import from linked financial institutions

list_account_transactions

List transactions for a specific account

list_category_transactions

List transactions for a specific category

list_payee_transactions

List transactions for a specific payee

list_month_transactions

List transactions for a specific month

Scheduled Transactions

Tool

Description

list_scheduled_transactions

List all scheduled/recurring transactions

get_scheduled_transaction

Get details for a scheduled transaction

create_scheduled_transaction

Create a new scheduled transaction

update_scheduled_transaction

Update a scheduled transaction

delete_scheduled_transaction

Delete a scheduled transaction

Payees

Tool

Description

list_payees

List all payees

get_payee

Get details for a single payee

update_payee

Update a payee's name

create_payee

Create a payee

Payee Locations

Tool

Description

list_payee_locations

List all payee GPS locations

get_payee_location

Get a single payee location

get_payee_locations_for_payee

Get all locations for a specific payee

Months

Tool

Description

list_months

List all budget months with summaries

get_month

Get detailed month info with category balances

Money Movements

Tool

Description

list_money_movements

List all money movements

get_month_money_movements

Get money movements for a specific month

list_money_movement_groups

List all money movement groups

get_month_money_movement_groups

Get money movement groups for a specific month

Workflows

Tool

Description

merge_category

Merge a source category into a target, moving all transactions and budgeted amounts (1 API call to preview)

delete_category

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_payments

Audit credit card and line-of-credit funding gaps for unexplained month-over-month drift, with optional auto-fix (1 API call)

audit_account_reconciliation

Diagnose an account's reconciliation state (cleared vs. bank balance, unreconciled txn list) with optional close-out

audit_budget_integrity

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 strict_ready_to_assign; with ask_before_bridging, borrowing is returned as proposals to answer with bridge_sources, and only limits apply to chosen repairs) (1 API call to audit)

plan_month

Set a month's assigned amounts by rules you pass, in order: spent (the month before's spending, with an optional fallback to its assigned amount and a floor at it) and goal (fund active goals; flags charges without goals, goals without charges and price changes); only Ready to Assign pays for increases, all_or_nothing or in_order (1 API call to plan)

suggest_categories

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

ynab://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

ynab://api-usage

Local rolling-hour estimates, next slot/cooldown and cached snapshot metadata; includes budget/preview guidance

0 HTTP

Budget Summary

ynab://budgets/{budget_id}/summary

Snapshot overview with provenance; up to 100 accounts/groups

Snapshot

Account List

ynab://budgets/{budget_id}/accounts

Account balances/status; up to 500 rows

Normally 1

Monthly Categories

ynab://budgets/{budget_id}/months/{month}/categories

Category amounts for one month; up to 500 rows

Normally 1

Category Month

ynab://budgets/{budget_id}/categories/{category_id}/months/{month}

One category-month with provenance and goal-history caveat

Snapshot

Account Transactions

ynab://budgets/{budget_id}/accounts/{account_id}/transactions/{since_date}/{until_date}/{limit}/{offset}

At most 366 days and 100 rows/page (byte bounds may return fewer), offset up to 10000; next_uri/truncated report output coverage, memos clipped to 200 characters with memo_truncated

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

monthly-review

budget_id, month

Review a budget month: overspent categories, spending variances, underfunded goals, CC mismatches

transaction-audit

budget_id, account_id, since_date

Audit transactions for uncategorized, unapproved, duplicates, and unusual amounts

budget-setup-guide

budget_id

Guided walkthrough: accounts, categories, targets, scheduled transactions, fund allocation

spending-analysis

budget_id, month

Category breakdown, budget vs. actual, top payees, income vs. spending

credit-card-audit

budget_id, since_month?

Audit CC payment category balances with dry-run-first, confirm-before-apply flow

reconcile-account

budget_id, account_id, target_balance

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 server

License

MIT, see LICENSE.

Available Tools

47 tools
audit_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 TransactionB
Destructive

[1 API call] Delete a scheduled transaction

Inputs: scheduled_transaction_id (required), budget_id.

delete_transactionDelete TransactionB
Destructive

[1 API call] Delete a transaction

Inputs: transaction_id (required), budget_id.

get_accountGet AccountB
Read-only

[1 API call] Get details for a single account

Inputs: account_id (required), budget_id.

get_api_usageGet API UsageA
Read-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 BudgetA
Read-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 SettingsB
Read-only

[1 API call] Get a budget's date and currency format settings

Inputs: budget_id.

get_categoryGet CategoryB
Read-only

[1 API call] Get details for a single category

Inputs: category_id (required), budget_id.

get_monthGet Budget MonthA
Read-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 CategoryB
Read-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 GroupsB
Read-only

[1 API call] Get money movement groups for a specific month

Inputs: month (required), budget_id.

get_month_money_movementsGet Month Money MovementsB
Read-only

[1 API call] Get money movements for a specific month

Inputs: month (required), budget_id.

get_payeeGet PayeeB
Read-only

[1 API call] Get details for a single payee

Inputs: payee_id (required), budget_id.

get_payee_locationGet Payee LocationB
Read-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 PayeeB
Read-only

[1 API call] Get all GPS locations for a specific payee

Inputs: payee_id (required), budget_id.

get_scheduled_transactionGet Scheduled TransactionB
Read-only

[1 API call] Get details for a single scheduled transaction

Inputs: scheduled_transaction_id (required), budget_id.

get_transactionGet TransactionB
Read-only

[1 API call] Get details for a single transaction

Inputs: transaction_id (required), budget_id.

get_userGet UserB
Read-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 AccountsA
Read-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 TransactionsB
Read-only

[1 API call] List transactions for a specific account

Inputs: account_id (required), budget_id, since_date, type, +1 more.

list_budgetsList BudgetsA
Read-only

[1 API call] List all budgets the user has access to, with optional account info

Inputs: include_accounts.

list_categoriesList CategoriesB
Read-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 TransactionsB
Read-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 GroupsB
Read-only

[1 API call] List all money movement groups for a budget

Inputs: budget_id.

list_money_movementsList Money MovementsB
Read-only

[1 API call] List all money movements for a budget (funds moved between categories)

Inputs: budget_id.

list_monthsList Budget MonthsA
Read-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 TransactionsB
Read-only

[1 API call] List transactions for a specific month

Inputs: month (required), budget_id, since_date, type, +1 more.

list_payee_locationsList Payee LocationsB
Read-only

[1 API call] List all payee GPS locations for a budget

Inputs: budget_id.

list_payeesList PayeesB
Read-only

[1 API call] List all payees for a budget

Inputs: budget_id, last_knowledge_of_server.

list_payee_transactionsList Payee TransactionsB
Read-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 TransactionsB
Read-only

[1 API call] List all scheduled (recurring) transactions for a budget

Inputs: budget_id, last_knowledge_of_server.

list_transactionsList TransactionsA
Read-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 CategoryA
Destructive

[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

    A3.5/5.0

    Scored across 47 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      B
      maintenance
      An 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.
      32
      6
      -
    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      9
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Exposes YNAB API endpoints as MCP tools, allowing AI assistants to manage budgets, accounts, transactions, and more through natural language.
      41
      279 PyPI
      101
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      1
      MIT