YNAB MCP server (Phase 1)

A local, read-only MCP server for one personal YNAB plan. It runs over stdio, fetches current data on demand from https://api.ynab.com/v1, and does not save financial data, cache responses, or send telemetry. Python 3.12+ and uv are required.

Set up

1. Create a YNAB Personal Access Token (PAT) in your YNAB account and keep it in your local MCP host configuration. The server does not load .env automatically. .env.example contains placeholders only; .env is ignored by Git.

2. In this audited checkout, run uv sync --frozen.

3. Set YNAB_PAT but leave YNAB_PLAN_ID unset, then start the server and call list_plans to find your plan UUID. Setup mode exposes only that tool.

4. Add the UUID to the host configuration and restart. For example, replace the path and placeholders locally:

{
  "mcpServers": {
    "ynab": {
      "command": "uv",
      "args": ["run", "--frozen", "--directory", "/absolute/path/to/ynab-mcp", "ynab-mcp"],
      "env": {
        "YNAB_PAT": "<set locally; never commit>",
        "YNAB_PLAN_ID": "<plan UUID>",
        "YNAB_READ_ONLY": "true"
      }
    }
  }
}

The configured server exposes list_accounts, get_budget_summary, list_categories, list_transactions, get_spending_summary, and get_uncategorized_transactions. All are read-only tools. YNAB_READ_ONLY defaults to true; setting it to any other value fails startup. Logging is fixed at WARNING; setting LOG_LEVEL fails startup. If you no longer need access or suspect exposure, revoke the PAT in YNAB and remove it from your host configuration.

Related MCP server: YNAB MCP Server

What the results mean

• Account balances and their on-budget, tracking, and combined totals are signed net balances, including liabilities. They are not spendable cash. Closed accounts are excluded by default; deleted accounts are always excluded.

• available_in_categories sums non-deleted, non-internal month-category balances, including hidden categories. Ready to Assign is separate. YNAB's documented category schema has no stable credit-card-payment discriminator, so internal credit-card-payment balances may be omitted. This number is neither cash available nor the sum of account balances.

• Spending is net expense-category outflows plus eligible uncategorized outflows on on-budget accounts; refunds reduce spending. Ordinary transfers between on-budget accounts, tracking-account postings, deleted rows, and Ready to Assign inflows are excluded. get_uncategorized_transactions shows actionable open-account outflows rather than every row lacking a category.

• Dates are inclusive and the current month uses UTC. A current-month bucket is month-to-date; compare it with the same days in the previous month for equal coverage. For example, compare September 1–13 with August 1–13, rather than all of August. Clamp the prior end date to its last calendar day when needed.

• Date ranges are limited to 366 days. Transaction tools return at most 500 rows, with truncated and complete flags; list_transactions omits memos unless include_memo=true. Aggregate tools require complete source data and return an error instead of a partial total when the bounded response cannot be processed. Money values are fixed-scale decimal strings in the plan currency.

Privacy boundary

The PAT itself is not provider-enforced read-only and can access any plan allowed by that token. The fixed plan UUID and GET-only routes constrain this server; they do not reduce the PAT's underlying permissions. The server has no YNAB write route, does not follow redirects, and does not take a caller-supplied URL. Its own no-persistence rule does not apply to your MCP host: financial results cross into the host and may enter its history or be sent to a remote model. Use a host whose data-handling policy you accept. Payee names, category names, and memos are untrusted data fields, not instructions to the assistant.

Verify this checkout

uv sync --frozen
uv run --frozen pytest
uv run --frozen ruff check .
uv run --frozen ruff format --check .
uv run --frozen mypy src
uv run --frozen pip-audit

The dependency audit is an explicit development/release check and may use the network. The running MCP server does not audit dependencies or phone home for that purpose. Tests use synthetic data and a fake PAT; no live YNAB account is needed.