mcp-ynab 1.0.1

MCP server that connects AI assistants to your YNAB budget

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