YNAB MCP Server

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

Tools

Core (daily budget management)

Tool	Description
`get_budgets`	List all budgets
`get_accounts`	List accounts with balances
`get_categories`	Category groups with budgeted/activity/balance
`get_payees`	List payees (for resolving names to IDs)
`get_month`	Monthly overview with per-category breakdown
`get_transactions`	Search transactions by date/account/category/payee
`create_transaction`	Add a new transaction
`update_month_category`	Change budgeted amount for a category

Extended (weekly/occasional)

Tool	Description
`update_transaction`	Edit existing transaction fields
`delete_transaction`	Delete a transaction
`create_transactions_bulk`	Create multiple transactions from JSON
`get_scheduled_transactions`	View recurring/upcoming bills
`create_account`	Add a new account
`get_budget_months`	Historical month list for trends
`update_category`	Change category name, note, or goal

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)

Push this repo to GitHub
Create a new Railway project and connect the repo
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
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).

ynab-mcp