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

• Node.js 20+
• A YNAB Personal Access Token

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" } } }

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.

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. 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..."},
    {"chain": "eth", "address": "0x..."},
    {"chain": "eth", "address": "0x...", "token": {"contract": "0xA0b8...", "decimals": 6, "coingecko": "usd-coin", "symbol": "USDC"}},
    {"chain": "sol", "address": "..."}
  ]}
]

Crypto uses public data only: mempool.space (BTC address), blockchain.info (BTC xpub/ypub/zpub; it learns the wallet's addresses), a public Ethereum RPC, Solana's public RPC, and CoinGecko prices. 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 /auth/get (account and routing numbers) and /identity/get are 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

Budgets

Accounts

Categories

Transactions

Scheduled Transactions

Payees

Payee Locations

Months

Money Movements

Workflows

| 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}).

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.

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.