v0.2.0 — install anywhere, and a place to start

v0.2.0 — install anywhere, and a place to start

The theme is reach and first contact: getting the server installed without
editing JSON, and giving an assistant somewhere to begin once it is.

Installing

• An MCPB bundle for desktop hosts. The host asks for the token in a form
  and stores it in the OS keychain, so there is no config file to edit and
  no credential left in plain text. A checkbox controls writes.
• A Claude Code plugin and marketplace: two commands, no JSON.
• A published container image for linux/amd64 and linux/arm64.
• Listed in the MCP Registry.

Every manifest that carries a version is generated from pyproject.toml and
checked in CI, so an install surface cannot quietly fetch a previous
release.

Using

• Six guided prompts, which most clients surface as slash commands:
  monthly review, weekly triage, categorize and approve, subscription
  audit, cash position, and review-and-undo.
• Three reference resources covering the YNAB method, write safety, and
  which tool to reach for. Fetched on demand, so they cost nothing until
  a client asks.
• Every tool now carries a readable title and an honest destructive hint,
  for the permission dialogs clients show before a call touches real data.

New tool

• analysis_recurring_charges answers what subscriptions actually cost per
  year. It groups by YNAB's payee id rather than payee names, so no fuzzy
  matching is involved, and it requires a consistent amount as well as a
  steady cadence — without that second test a weekly grocery run reads as
  a subscription.

Correctness

• Text YNAB returns HTML-escaped is decoded on the way in, so a payee reads
  as B&H Photo Video. Writes still send exactly what the caller supplied.
• Write field lengths are checked against YNAB's own limits before the
  request leaves, which matters most in bulk writes where one over-long
  memo otherwise fails the whole batch.
• Invalid arguments are reported as validation errors naming the field,
  rather than as internal errors.

Verified against the live YNAB API across every read-only tool, and from a
clean install of the wheel, the sdist, and the container image.

v0.1.0 — MCP Server for YNAB

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.