MCP Server for YNAB

An AI-first Model Context Protocol server for YNAB. It exposes the YNAB API as MCP tools, then adds enriched tools that answer questions the raw API cannot answer in one call — budget health, cleanup queues, spending analysis.

Read-only by default. Write tools are not registered unless you set YNAB_ALLOW_WRITES=1, so an agent cannot change your budget until you say so. See Write Tools.

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, 44 tools registered.

2. Add it to your client

The two most common paths:

Claude Code — one command:

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.

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.

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. Call overview_request_budget to see what is left; it costs no API requests.

Tool Families

44 read-only tools, 63 with writes enabled.

Raw tools are close mirrors of YNAB endpoints — use them for exact reads and all writes. Enriched tools combine several reads into one answer — use them for orientation, investigation, and analysis. Every tool is labeled read or write, and enriched tools perform no hidden writes.

More detail: Tool Surface

Write Tools

Write tools are not registered unless you opt in:

YNAB_ALLOW_WRITES=1

Without it the server is read-only, and the write tools are absent from tools/list — an agent cannot call what it cannot see. This is deliberate: the server holds a credential that can modify real financial records, and refusing a call at execution time would still advertise the capability.

Every write is recorded, and most can be undone

When writes are enabled, each one records the state that existed before it. YNAB has no history endpoint, so this is the only way to get an overwritten value back.

history_revert_to undoes everything after the entry you name, newest first, because overlapping edits to the same record only compose correctly in reverse. Reverting is itself recorded, so a revert can be reverted.

What cannot be undone. YNAB has no delete route for accounts, categories, category groups, or payees, so creating one is permanent. Those operations are recorded as non-revertible with the reason, and a rollback reports them under blocked rather than skipping them silently — an incomplete rollback that claims success is worse than one that tells you what it left behind. A recreated transaction also gets a new id and loses any bank-import link.

Writes are checked, not assumed

Tools that change a value re-read it afterwards and report a verification block. A 200 response is not proof: YNAB accepts budgeted on the category update route, returns 200, and ignores it. Verification is what catches that.

Amount Convention

All YNAB monetary amounts are in milliunits: 1000 = $1.00.

• Raw tools accept and return milliunits for canonical amount fields.
• Enriched tools may include display helpers alongside canonical values.

Your Data

This server stores exactly one thing on your machine: a record of the writes it made, used by history_revert. Nothing is sent anywhere except api.ynab.com, and there is no telemetry.

uvx mcp-server-for-ynab history --show          # where it is, how much is there
uvx mcp-server-for-ynab history --export out.json
uvx mcp-server-for-ynab history --delete        # also removes the ability to revert

These need no credentials and no agent: getting your data back, or gone, should not require running an LLM.

For Contributors

This repo is structured so a contributor or AI agent can answer three questions quickly: where the MCP server lives, where the YNAB API wrappers and models live, and where to add new tools, tests, and docs.

flowchart LR
    A["MCP Client"] --> B["FastMCP Server"]
    B --> C["Tool Handlers"]
    C --> D["ynab_client"]
    D --> E["http_client (httpx)"]
    E --> F["YNAB API"]
    C --> G["enriched/"]
    G --> D

The code is centered on a small set of layers:

• src/mcp_server_for_ynab/server/: FastMCP app, tool metadata, tool registration, error boundary
• src/mcp_server_for_ynab/ynab_client/: one async wrapper module per YNAB resource family
• src/mcp_server_for_ynab/http_client/: outbound httpx wrapper with retries, redaction, and error normalization
• src/mcp_server_for_ynab/models/: typed YNAB shapes, shared error model, milliunit helpers
• src/mcp_server_for_ynab/enriched/: higher-level read-only workflows built on top of raw clients
• tests/: unit, contract, integration, and QA/Postman source assets

Run it from a clone:

git clone https://github.com/hs737/mcp-server-for-ynab
cd mcp-server-for-ynab
uv sync
cp .env.example .env    # then set YNAB_API_KEY

make smoke-stdio
make run-stdio
make run-http

Run the tests:

make test
make test-unit
make test-contract
make test-integration
make test-postman-operator

Where to read next

If you are:

• connecting a client: Client Setup
• new to the repo: Architecture
• adding code: Contributing, Repo Structure, Agent Guidance
• adding or changing tools: Tool Surface
• verifying behavior: Testing
• working on auth, error handling, or logging: Security

Full map: Docs Index. Also: Postman Notes, Legal Notice.

Current State

The current implementation uses Python 3.12, FastMCP from the official mcp package, asyncio end to end, httpx for outbound YNAB calls, and the built-in stdio and streamable HTTP transports.

This is a local, personal-access-token server. A hosted or public connector is not implemented — that includes ChatGPT custom connectors, which require a remote HTTPS endpoint rather than a local process. The intent is for a hosted runtime to live in its own repository, importing this package through its embed surface so OAuth and public-app concerns stay out of here.

If architecture and implementation ever diverge, the source of truth should be Architecture, updated to reflect the actual code.

License

Apache License 2.0. See LICENSE and NOTICE.md.

Disclaimer

We are not affiliated, associated, or in any way officially connected with YNAB or any of its subsidiaries or affiliates. The official YNAB website can be found at https://www.ynab.com.

The names YNAB and You Need A Budget, as well as related names, tradenames, marks, trademarks, emblems, and images are registered trademarks of YNAB.