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

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