YNAB MCP Server

An MCP server for YNAB with batch operations, deterministic analysis tools, and robust undo support.

[!NOTE] AI Disclosure: This project was built with Claude Code and Cursor. It works and is tested, but the code is largely clanker-made.

Highlights

• 26 tools covering budgets, accounts, transactions, categories, targets, scheduled transactions, and spending analysis
• Deterministic analysis — spending aggregation, trends, income vs expense, recurring-charge and anomaly detection, and a one-call budget health snapshot. Judgment calls (forecasting, reallocation, prioritization) are deliberately left to the calling agent, which has the exact data and more context
• Batch operations — create, update, and delete multiple transactions in a single call, with per-item API costs documented where the YNAB API has no bulk endpoint
• Undo support — every write operation is recorded and reversible
• Smart categorization — transaction category suggestions from payee history and scheduled-transaction matching, with confidence gating so only high-confidence suggestions land in the ready-to-apply actions
• Built-in knowledge base — YNAB methodology docs (credit cards, targets, overspending, reconciliation) served as MCP resources
• 5 workflow prompts — monthly reviews, spending reports, unapproved triage, budget optimization, and subscription audits
• Read-only mode — write tools are not even registered, so clients only see tools they can use
• Efficient caching — delta sync with YNAB's server knowledge system, configurable TTLs, and client-side rate-limit tracking

Setup

Prerequisites

• Node.js >= 20
• A YNAB personal access token

Usage

Run directly with npx:

YNAB_API_TOKEN=your-token npx @maro-org/ynab-mcp

Or install globally:

npm install -g @maro-org/ynab-mcp
YNAB_API_TOKEN=your-token ynab-mcp

MCP Client Configuration

Add the server to your MCP client config. For example, in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@maro-org/ynab-mcp"],
      "env": {
        "YNAB_API_TOKEN": "your-token"
      }
    }
  }
}

For Cursor, add the same structure to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally.

Configuration

All configuration is done through environment variables.

Tools

Budgets

Accounts

Transactions

Categories

Spending Analysis & Diagnostics

All analysis tools are deterministic — no LLM sampling involved. They report facts and clearly-labeled statistical estimates; forecasting and reallocation decisions are left to the calling agent (the workflow prompts walk it through that reasoning using get_targets, get_monthly_budget, and get_scheduled_transactions).

Scheduled Transactions

Smart Tools

Suggestions carry confidence levels; only those at or above action_confidence (default high) are included in the ready-to-apply update_actions, and approval is opt-in.

Undo

Resources

Knowledge base resources for YNAB methodology. Workflow prompts reference these automatically.

Prompts

Key Concepts

Currency units — All monetary amounts in tool inputs and outputs use standard currency units (e.g., 12.50), not YNAB's native milliunits. Most tools also echo a top-level currency ISO code; get_spending_analysis additionally reports raw *_milliunits totals alongside them.

`budget_id` — Most tools accept an optional budget_id. Omit it or pass "last-used" to target the most recently accessed budget.

Undo — Every write operation records an undo entry. Use list_undo_history and undo_operations to review or revert changes. The most recent 2000 entries per budget are kept (tunable via YNAB_UNDO_HISTORY_LIMIT).

Read-only mode — Set YNAB_READ_ONLY=true to hide and block all write operations. Useful for exploring your budget safely or restricting an MCP client to read-only access.

Rate limiting — The YNAB API allows 200 requests per rolling hour. The server tracks usage locally and reports when capacity frees up if the limit is reached. (The API used to expose an X-Rate-Limit header the tracker reconciled against; the live API no longer sends it, so the local tracker is the sole signal until a 429 confirms exhaustion.) Tools that cost one API call per item say so in their descriptions.

Development

npm install
npm run dev        # run with tsx watch
npm run build      # compile TypeScript
npm test           # run tests (vitest)
npm run typecheck  # type-check without emitting
npm run lint       # lint with Biome
npm run ci         # typecheck + lint + test

License

MIT