ynab-mcp

An MCP (Model Context Protocol) server for YNAB (You Need A Budget), so an LLM client such as Claude Desktop can analyze your budget, accounts, categories, and transactions.

Status: early work in progress. All planned tool areas are implemented: read-only budget analysis, category management, transaction management, and account/budget setup. The one thing not yet done is a manual end-to-end pass through Claude Desktop against a real budget (everything else is covered by the automated test suite).

What it can do today

There is intentionally no ynab_delete_category and no ynab_close_account/ynab_update_account: YNAB's public API has no delete endpoint for categories, no hidden field to hide one either, and no update or close endpoint for accounts at all — AccountsApi in the underlying SDK only exposes create/get/list. Once you create an account or category with this server, there's no way to close, hide, or delete it through the API (or any other API client) — you'd need to do that from the YNAB app itself.

Delta sync: the list tools marked above accept an optional last_knowledge_of_server input and always return a server_knowledge value in their result. Save that value and pass it back in on your next call to that tool to receive only the entities that changed since then, instead of re-fetching the whole collection — useful if you're polling the same budget repeatedly and want to stay well under YNAB's 200-requests/hour rate limit.

Error messages: every tool error includes a short note on whether retrying makes sense — rate-limit (429) and network errors say to back off and retry later, everything else (bad ids, auth failures, validation errors) says retrying the same call won't help and what to check instead.

Related MCP server: ynab-mcp

Setup

Prerequisites

• Node.js >= 20

• pnpm (this repo pins pnpm@10.33.0 via the packageManager field)

• A YNAB Personal Access Token (YNAB web app → Account Settings → Developer Settings → New Token)

Install and build

pnpm install
pnpm build

This produces dist/index.js, an executable Node script (it also has a bin entry, so once published you'll be able to run it via npx ynab-mcp).

Configure Claude Desktop

Add the server to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "ynab": {
      "command": "node",
      "args": ["/absolute/path/to/ynab-mcp/dist/index.js"],
      "env": {
        "YNAB_ACCESS_TOKEN": "<your personal access token>"
      }
    }
  }
}

Restart Claude Desktop and the ynab_* tools should be available.

Environment variables

Safety

• Category and transaction management tools create and modify data in your live budget. Create/update tools are annotated readOnlyHint: false, destructiveHint: false (data isn't lost, just changed).

• ynab_delete_transaction is the one destructive tool implemented so far: it's annotated destructiveHint: true, requires an explicit confirm: true field in the tool call (calls without it are rejected before any request reaches YNAB), and returns the deleted transaction's fields in the result so the call is auditable afterwards. Host-level tool-call approval (e.g. in Claude Desktop) remains the primary line of defense against a bad or malicious tool call — the confirm field is defense-in-depth, not a substitute for it.

• YNAB personal access tokens are not scoped — there's no way to grant this server read-only or budget-limited access. It gets full read/write access to your entire YNAB account, same as the YNAB app itself.

• Your access token is read once from the YNAB_ACCESS_TOKEN environment variable at startup and is never logged or written to disk by this server.

Development

pnpm dev         # watch mode, restarts the server on change
pnpm typecheck   # tsc --noEmit
pnpm lint        # oxlint
pnpm format      # oxfmt
pnpm test        # unit + integration tests (vitest)

The integration tests (test/integration/server.test.ts) run the real MCP server against the real ynab SDK, with MSW mocking the underlying HTTP calls to api.ynab.com — no live network access or real YNAB account needed to run pnpm test.

pnpm test:live is reserved for opt-in tests against a real YNAB account (gated behind env vars, excluded from pnpm test), but that test suite hasn't been written yet — running it today will just report "no test files found."

See CLAUDE.md for architecture notes.

License

MIT