Skip to content

v0.1.0 — MCP Server for YNAB

Choose a tag to compare

View all tags
@hs737 hs737 released this 28 Aug 12:30
· 12 commits to master since this release
v0.1.0
334f4ab

First public release of 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.

Install

Nothing to clone — uvx fetches and runs it in a throwaway environment:

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

Then add it to your client. Client Setup covers Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI, Gemini CLI, Windsurf, and Zed.

Read-only by default

44 read-only tools out of the box; 63 once YNAB_ALLOW_WRITES=1 is set. Until then the write tools are not registered at all, so they never appear in tools/list — an agent cannot call what it cannot see. Refusing at execution time would still have advertised the capability, and the server holds a credential that can modify real financial records.

Enriched tools

Beyond close mirrors of the YNAB endpoints, single-call answers to the questions people actually ask: budget health, cash position, uncategorized and unapproved queues, overspent categories, target funding gaps, and scheduled-transaction risks. Agents should start with overview_available_tools.

Writes are reversible, and verified

  • Every write records the state that preceded it. YNAB has no history endpoint, so this is the only way to get an overwritten value back. history_revert undoes one write; history_revert_to rolls back to a chosen point, newest first, because overlapping edits to the same record only compose correctly in reverse.
  • What YNAB cannot undo is recorded as non-revertible with the reason, and a rollback reports it under blocked. An incomplete rollback that claims success is worse than one that says what it left behind.
  • Tools re-read what they changed and report a verification block. A 200 is not proof: YNAB accepts budgeted on the category update route, returns 200, and ignores it.

Rate limits

YNAB allows 200 requests per hour per token. The server tracks its own usage in a rolling hour and stops at 190, so the limit you hit is a clear local error rather than a 429 partway through a workflow. overview_request_budget reports what is left and costs nothing.

Your data

Nothing is sent anywhere except api.ynab.com, and there is no telemetry. The only thing stored is the local write history, which the CLI can show, export, or delete without credentials or an agent.

Verification

Checked against the live YNAB API across every read-only tool, and from a clean install of both the built wheel and the sdist. Published via PyPI Trusted Publishing.

Requires Python 3.12+. Full documentation: README · Tool Surface · Architecture

Not affiliated, associated, or in any way officially connected with YNAB. The official YNAB website is https://www.ynab.com.

Assets 2
Loading