YNAB Conversation MCP

Talk through your budget. Put the changes into YNAB.

Connect Claude or Codex to your YNAB plan with Model Context Protocol. Review spending, assign money, move funds between categories, and update transactions as you talk.

Run it on your computer, or deploy your own private Cloudflare endpoint that stays available when your laptop is off.

“Help me budget this month. Start with what's available and which categories need attention.”

“Move $40 from dining out to groceries.”

“Find my uncategorized transactions and help me categorize them.”

Example prompts only—no personal budget data is included in this repository.

Choose your setup

The Cloudflare deployment is for one owner and one YNAB token. Each person should deploy their own instance. This is an independent community project, not affiliated with YNAB, Anthropic, or OpenAI.

Related MCP server: YNAB MCP Server

Local installation

You'll need Node.js 22 or newer, pnpm 11.24.0 (the version pinned in this project), and a YNAB personal access token. See pnpm installation if needed.

git clone https://github.com/itsRoze/ynab-mcp.git
cd ynab-mcp
pnpm install --frozen-lockfile
pnpm run build
pnpm run setup
pnpm run doctor
pnpm run config

1. Create a token in YNAB → Account Settings → Developer Settings. Enter it at the hidden setup prompt, not in an agent conversation.

2. doctor verifies authentication with a read-only call; it does not print your financial data.

3. config offers a menu for Codex, Claude Code, both, or Claude Desktop, and installs the configuration for you. Restart your client or start a new session afterward.

The setup command saves your token in a Git-ignored .env file with owner-only permissions and refuses to overwrite it. Client configuration references that file rather than copying the token. Desktop configuration is backed up before changes.

Prefer a direct command? Use pnpm run config --client codex, --client claude, --client both, or --client desktop. Use pnpm run config --print codex to inspect manual configuration. If you move the checkout or your Node installation, rerun configuration.

Read-only local mode: set YNAB_READ_ONLY=true in .env to omit write tools. Writes are otherwise enabled. The hosted deployment currently exposes both read and write tools.

Use it from anywhere

Deploy to Cloudflare →

The guide covers account setup, OAuth storage, secret installation, connecting clients, updates, and troubleshooting. Once deployed, your client connects to your own URL:

https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev/mcp

The YNAB token stays on the server. Sign in using a separate generated connector password. Remote client availability, including mobile, depends on the client's custom connector support and your account.

What it can do

• Understand your budget: plans, accounts, categories, targets, monthly totals, and Ready to Assign.

• Find spending: transactions by date and filters, individual transaction details, and upcoming scheduled transactions.

• Budget together: set monthly assigned amounts and move available money between categories.

• Keep things tidy: create or update transactions; change category names, notes, and target amounts.

Full tool reference and write behavior →

Amounts use exact decimal strings in your plan's currency. Budget changes check fresh assignments before writing, and transaction creation supports retry deduplication. Client permissions still apply; the server itself does not add a confirmation dialog.

Know the limits: moving money requires two YNAB writes and can partially succeed. An uncertain write is never automatically retried. Avoid simultaneous edits across clients and the YNAB app. Transaction deletion, split editing, scheduled-transaction editing, and advanced target cadence editing are not supported.

Privacy

Your token is sent only to the official YNAB API over HTTPS; redirects are rejected. Financial responses are not persisted by this server. Local mode has no telemetry. Cloudflare mode stores OAuth grants and consent state and enables sampled operational logs/traces, without application logging of tokens, passwords, request bodies, or financial results.

Your AI provider receives the tool results it requests. Keep .env, .env.remote, wrangler.private.json, and local runtime files private; they are excluded from Git. Never attach real budget exports or credentials to issues.

Development

pnpm install --frozen-lockfile
pnpm test                 # Build, unit tests, and stdio MCP integration
pnpm run check:worker     # Worker type checking
pnpm run test:remote      # Local Workers runtime: OAuth + MCP integration
pnpm pack --dry-run       # Inspect package contents

Tests use synthetic data and run without YNAB credentials. CI checks Node.js 22 and 24. See CONTRIBUTING.md for the development workflow and SECURITY.md for private vulnerability reporting.

License & references

MIT. Source installation is supported; no published npm package is required.

YNAB API · MCP · Claude Code MCP · Codex MCP

“Plan” and “budget” refer to the same YNAB concept here.