MCP Server for YNAB

MCP Server for YNAB

Ask your budget a question. Connect Claude, Codex, Cursor, or any MCP client to YNAB and get answers about your actual money — how the month is going, what is overspent, what your subscriptions really cost.

YNAB_API_KEY=your_token uvx mcp-server-for-ynab smoke

Read-only by default. The write tools are not registered at all unless you set YNAB_ALLOW_WRITES=1, so they never appear to the assistant and nothing can change your budget until you say so. When you do enable them, every write records the state that preceded it and can be undone.

An MCP server that exposes the YNAB API as tools, then adds enriched tools answering questions the raw API cannot answer in one call — budget health, cleanup queues, spending analysis, recurring charges.

Quick Start

1. Get a YNAB token

Generate a personal access token at app.ynab.com/settings/developer.

You also need uv, which provides uvx:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS and Linux

brew install uv # macOS with Homebrew winget install --id=astral-sh.uv -e # Windows

Check both work. Nothing to clone — uvx fetches the package and runs it in a throwaway environment:

YNAB_API_KEY=your_token uvx mcp-server-for-ynab smoke

smoke validates configuration and tool registration, then exits. It should print smoke: app created, 62 tools registered.

2. Add it to your client

The two most common paths:

Claude Code — install the plugin, which brings its own MCP config:

/plugin marketplace add hs737/mcp-server-for-ynab

/plugin install mcp-server-for-ynab@mcp-server-for-ynab

Or register the server directly, if you would rather not use a plugin:

claude mcp add --env YNAB_API_KEY=your_ynab_token --transport stdio --scope user \

ynab -- uvx mcp-server-for-ynab stdio

Claude Desktop, Cursor, Windsurf, and most others — paste into the client's MCP config file:

{

"mcpServers": { "ynab": { "command": "uvx", "args": ["mcp-server-for-ynab", "stdio"], "env": { "YNAB_API_KEY": "your_ynab_token", "YNAB_PLAN_ID": "your_plan_id" } } } }

YNAB_PLAN_ID is optional but recommended — with it set, you never have to name a budget in a request. Full per-client instructions, including where each config file lives and how to keep the token out of it, are in Client Setup.

Desktop hosts that accept bundles — download the .mcpb file from the latest release and open it. The host asks for your token in a form and stores it in your OS keychain, so there is no config file to edit and no token sitting in plain text. A checkbox controls whether writes are enabled.

Docker

A published image is available for linux/amd64 and linux/arm64. The server speaks MCP over stdin and stdout, so run it attached with -i. There is no port to publish:

docker run -i --rm -e YNAB_API_KEY=your_ynab_token \

ghcr.io/hs737/mcp-server-for-ynab

Or build it yourself from a clone:

docker build -t mcp-server-for-ynab .

docker run -i --rm -e YNAB_API_KEY=your_ynab_token mcp-server-for-ynab

If you enable writes, mount a volume for the history — otherwise --rm discards the record that makes a revert possible:

docker run -i --rm -e YNAB_API_KEY=your_ynab_token -e YNAB_ALLOW_WRITES=1 \

-v ynab-mcp-history:/home/app/.mcp-server-for-ynab mcp-server-for-ynab

3. Ask it something

What's my cash position across all accounts?

If that works, you're set. If it doesn't, see Troubleshooting — the usual cause is that the client cannot find uvx on its PATH.

What You Can Ask

Read-only, works out of the box:

With YNAB_ALLOW_WRITES=1:

Categorize last week's uncategorized transactions, then show me what you changed.

The agent categorizes, and history_list shows every write with the value that preceded it. history_revert undoes any of them.

Agents work best when they start with overview_available_tools, which returns the current tool catalog grouped by family. See Tool Surface for the full map.

Guided workflows

Seven prompts ship with the server, and most clients surface them as slash commands — a starting point that does not require reading the tool list first: monthly review, weekly triage, categorize and approve, subscription audit, cash position, review-and-undo, and a multi-month budget audit.

Four resources (ynab://guide/*) carry the YNAB method, the write-safety rules, guidance on which tool to reach for, and how credit accounts behave. They are fetched on demand, so they cost nothing until a client asks for them.

Configuration

Set these in your MCP client's env block. For local development, copy .env.example to .env and fill it in.

Rate limits

YNAB allows 200 requests per hour per token, and a single enriched tool can spend several. The server tracks its own usage in a rolling hour and stops just below YNAB's ceiling, so the limit you hit is local and clearly reported rather than a 429 in the middle of a workflow.

Every tool response carries requests_used_this_hour and requests_remaining, the way an HTTP API returns X-RateLimit-Remaining — an agent paces itself against a number it can already see, where asking for it costs a call it will not make. overview_request_budget adds the limit, the window, and when an exhausted budget reopens; ping answers whether the server is up at all. Both cost nothing.

The quota belongs to the access token, so your own YNAB apps spend from it too. The count here is what this server used, which can be less than what YNAB has left — every rate-limit error says so, and carries the reopening time as an absolute timestamp as well as a delay, so a scheduled retry does not come back early.

Tool Families

62 read-only tools, 84 with writes enabled, plus 7 guided prompts and 4 reference resources.

Raw tools are close mirrors of YNAB endpoints — use them for exact reads and most writes. Enriched tools combine several reads into one answer — use th