YNAB MCP Server

An MCP server that connects AI assistants to your YNAB budget. Ask your budget questions YNAB can't answer.

mcp-ynab.com — Full setup guide, troubleshooting, and more.

Features

30+ tools — budgets, accounts, transactions, categories, payees, months, scheduled transactions, and analytics
Delta sync — only fetches what changed since the last call (uses YNAB's server knowledge)
4-tier caching — TTL cache, delta sync, retry with backoff, SQLite persistence
Search & analytics — text search across transactions, per-category spending breakdowns, Sankey flow data
Bulk operations — create or update multiple transactions in a single call
Dollar amounts — accepts dollars in parameters, converts to YNAB milliunits internally

Quick Start

uv tool run mcp-ynab

Requires a YNAB personal access token set as YNAB_API_KEY.

Configuration

Claude Desktop / ChatGPT

Add to your config file:

{
  "mcpServers": {
    "ynab": {
      "command": "uv",
      "args": ["tool", "run", "mcp-ynab"],
      "env": {
        "YNAB_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

claude mcp add-json ynab --scope user '{"type":"stdio","command":"uv","args":["tool","run","mcp-ynab"],"env":{"YNAB_API_KEY":"your-api-key-here"}}'

See mcp-ynab.com for config file locations and troubleshooting.

Available Tools

Group	Tools
User	`get_user`
Plans	`list_plans`, `get_plan`, `get_plan_settings`
Accounts	`list_accounts`, `get_account`, `create_account`
Categories	`list_categories`, `get_category`, `create_category`, `update_category`, `create_category_group`, `update_category_group`, `get_category_for_month`, `update_category_for_month`
Payees	`list_payees`, `get_payee`, `update_payee`
Payee Locations	`list_payee_locations`, `get_payee_location`, `get_payee_locations_by_payee`
Months	`list_months`, `get_month`
Money Movements	`list_money_movements`, `get_money_movements_for_month`, `list_money_movement_groups`, `get_money_movement_groups_for_month`
Transactions	`list_transactions`, `get_transaction`, `get_transactions_by_account`, `get_transactions_by_category`, `get_transactions_by_month`, `get_transactions_by_payee`, `search_transactions`, `create_transaction`, `create_transactions`, `update_transaction`, `update_transactions`, `delete_transaction`, `import_transactions`
Scheduled	`list_scheduled_transactions`, `get_scheduled_transaction`, `create_scheduled_transaction`, `update_scheduled_transaction`, `delete_scheduled_transaction`
Analytics	`get_money_flow`, `get_spending_by_category`

Field selection

Every tool that returns a model accepts an optional exclude_fields list. By default each tool returns a sensible subset of fields to keep token usage low. See FIELDS.md for per-model defaults and override examples.

Development

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run server standalone
uv run python -m src.server

Requires YNAB_API_KEY in .env.local for running the server.

License

AGPL-3.0