rogo-ynab-mcp 0.7.0

MCP server for YNAB API

ynab-mcp

MCP server exposing YNAB budget data to Claude.

Status

Maintained on a best-effort basis for the YNAB API v1. It is feature-complete for its scope (the tools listed below); there is no roadmap for broader coverage. Bug reports and merge requests are welcome and reviewed as time allows, but timely responses are not guaranteed. Breaking changes are released under a new major version and recorded in CHANGELOG.md. To report a security issue, see SECURITY.md.

Tools

Tool	Description
list_budgets	List all budgets
list_accounts	List accounts for a budget
get_month_summary	Current month budgeted vs spent by category group
list_transactions	Recent transactions (filterable by account/date)
list_categories	Categories with budgeted and activity amounts
create_transaction	Add a new transaction (idempotent — identical retries are deduplicated, not duplicated)

Requirements

• Python >= 3.12 (managed by uv/uvx)
• A YNAB Personal Access Token (YNAB → Settings → Developer Settings)
• Any OS: the token is read from the YNAB_TOKEN environment variable; on macOS the Keychain is supported as the recommended storage

Setup

1. Provide the YNAB token

Cross-platform (environment variable):

export YNAB_TOKEN="<your-token>"

macOS (Keychain, recommended — no token in shell profiles):

security add-generic-password -s "ynab-mcp" -a "ynab-token" -w "<your-token>"

The env var takes precedence when both are set.

2. Add to Claude Code (~/.claude/settings.json)

Installed from PyPI (recommended):

"mcpServers": {
  "ynab": {
    "type": "stdio",
    "command": "uvx",
    "args": ["rogo-ynab-mcp"]
  }
}

Or from a source checkout: uv sync, then use "command": "uv", "args": ["run", "--project", "/path/to/ynab-mcp", "rogo-ynab-mcp"].

Client compatibility

This is a standard stdio MCP server launched with uvx rogo-ynab-mcp, so any MCP client that supports the stdio transport should work. Only the Claude Code setup is documented and exercised here; the others use the same command and are expected to work but are not separately verified.

Client	Status	Notes
Claude Code	Documented / used	Config shown in Setup (~/.claude/settings.json).
Claude Desktop	Expected to work	Add the same mcpServers block to claude_desktop_config.json.
Cursor	Expected to work	Register as an MCP server (stdio): command uvx, args ["rogo-ynab-mcp"].
Antigravity	Expected to work	Register as an MCP server (stdio): command uvx, args ["rogo-ynab-mcp"].
Generic MCP clients	Expected to work	Any client speaking the MCP stdio transport; point it at uvx rogo-ynab-mcp.

Usage

Once the server is registered, ask your MCP client in natural language — it picks the right tool and fills in the arguments. Example prompts:

• "Which YNAB budgets can you see?" → list_budgets
• "What's the balance on my checking account?" → list_accounts
• "How am I doing against my budget this month?" → get_month_summary
• "How much did I spend on groceries this month?" → list_categories
• "Show my transactions since the start of the month." → list_transactions
• "Add a 45.90 expense at Sample Coffee to checking, dated today." → create_transaction

Sample tool output

Amounts are returned as plain numbers in the budget's currency (YNAB milliunits are converted for you). Values below are illustrative fakes.

list_transactions:

[
  {
    "id": "b1f2c3d4-5678-49ab-9cde-1234567890ab",
    "date": "2026-07-03",
    "amount": -45.9,
    "payee": "Sample Coffee",
    "category": "Dining Out",
    "account": "Everyday Checking",
    "memo": null,
    "approved": true
  }
]

create_transaction (retries are idempotent — an identical call returns a duplicate marker instead of creating a second transaction):

{
  "duplicate": false,
  "id": "9c3d5e7f-1a2b-4c8d-8e9f-abcdef012345",
  "date": "2026-07-06",
  "amount": -45.9,
  "payee": "Sample Coffee"
}

Development

uv run pytest                         # run tests with coverage
uv run pytest --cov-report=html       # HTML coverage report

License

Apache-2.0