YNAB MCP Server

MCP server for YNAB (You Need A Budget) — manage budgets, accounts, categories, and transactions through Claude.

Tools

Core (daily budget management)

Extended (weekly/occasional)

Setup

1. Get a YNAB Personal Access Token

Go to YNAB Settings > Developer Settings and create a Personal Access Token.

2. Configure environment

cp .env.example .env
# Edit .env and set YNAB_ACCESS_TOKEN

3. Run locally

# stdio transport (Claude Desktop / Claude Code)
uv run server.py

# HTTP transport (Claude.ai connector / remote access)
uv run server.py --transport streamable-http

4. Claude Desktop configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ynab": {
      "command": "uv",
      "args": ["run", "/path/to/ynab-mcp/server.py"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Deployment (Railway)

1. Push this repo to GitHub

2. Create a new Railway project and connect the repo

3. Set environment variables in Railway:

   • YNAB_ACCESS_TOKEN — your YNAB Personal Access Token

   • YNAB_DEFAULT_BUDGET_ID — (optional) default budget UUID or "last-used"

   • MCP_BEARER_TOKEN — (optional) secure the MCP endpoint

4. Railway auto-deploys on push to main

The server reads the PORT environment variable (set automatically by Railway).

Multi-User Support

Set per-user tokens to give each person their own connector URL:

YNAB_TOKEN_ADAM=adams-token
YNAB_TOKEN_SARAH=sarahs-token

URL routing:

• /adam/mcp — uses YNAB_TOKEN_ADAM

• /sarah/mcp — uses YNAB_TOKEN_SARAH

• /mcp — uses YNAB_ACCESS_TOKEN (default)

Currency Format

YNAB uses milliunits (1/1000 of a currency unit):

• $10.00 = 10000 milliunits

• -$5.50 = -5500 milliunits

All tool responses include both raw milliunit values and formatted display strings (e.g., balance and balance_display).

Rate Limits

YNAB allows 200 requests per hour per access token. The server returns friendly error messages when rate limited (HTTP 429).