YNAB MCP worker

A remote MCP server for YNAB. It runs on Cloudflare Workers and connects to Claude as a custom connector. Once connected, it works in Claude on the web, desktop, and mobile.

It runs on Cloudflare’s free tier. There is no container and no monthly host to keep online.

This repository is a live deployment. If you fork it, change the worker name and KV namespace before you deploy.

How it works

Claude  --OAuth-->  this Worker  --YNAB personal access token-->  api.ynab.com
                         |
                   AUTH_PASSPHRASE
                 (typed once, on consent)

• Your YNAB personal access token stays in Cloudflare’s encrypted secret store. The Worker uses it for server-to-server calls. Claude never sees it.

• Claude authenticates with OAuth. The first connection shows a consent screen; you type a passphrase. After that, Claude uses short-lived access tokens and rotating refresh tokens.

• The passphrase is the only thing that protects the Worker URL. Use a long random value. Anyone who finds the URL and the passphrase can do whatever your YNAB token can do.

OAuth (registration, PKCE, tokens, refresh) comes from @cloudflare/workers-oauth-provider. This repo adds the consent screen and the MCP tools.

Related MCP server: YNAB MCP Server

Tools

Amounts in tool arguments and responses are ordinary currency (-42.50), not YNAB milliunits.

Always available

When YNAB_ALLOW_WRITES is "true"

Transactions: create_transaction, update_transaction, bulk_update_transactions, delete_transaction, import_transactions
Scheduled: create_scheduled_transaction, update_scheduled_transaction, delete_scheduled_transaction
Budget: set_category_budget, move_money, update_category, create_category, create_category_group, update_category_group
Accounts and payees: create_account, update_payee, merge_payees

Writes are gated twice: the Worker flag, and the OAuth scope on the Claude connection (ynab:read vs ynab:write). A read-only connection does not list write tools.

Fork and deploy

You need a YNAB personal access token and a free Cloudflare account.

If you forked this repo, do these first:

1. Change "name" in wrangler.jsonc. That name becomes your *.workers.dev URL.

2. Create your own KV namespace (npx wrangler kv namespace create OAUTH_KV) and paste the id into wrangler.jsonc. Do not reuse the id already in this file.

3. Keep "YNAB_ALLOW_WRITES": "false" until you have watched the read tools against your own budget.

Generate a passphrase and store it somewhere safe:

openssl rand -base64 24

CLI

npm install
npx wrangler login
npx wrangler kv namespace create OAUTH_KV   # paste the id into wrangler.jsonc
npx wrangler secret put YNAB_ACCESS_TOKEN
npx wrangler secret put AUTH_PASSPHRASE
npx wrangler deploy

Wrangler prints a URL such as https://ynab-mcp-worker.your-subdomain.workers.dev.

One-click (Cloudflare dashboard)

After a fork, change the button URL to your fork. Cloudflare creates the KV namespace, asks for the two secrets, and deploys.

GitHub Actions

.github/workflows/deploy.yml typechecks, tests, and deploys on push to main. Add one repo secret: CLOUDFLARE_API_TOKEN. Do not put YNAB_ACCESS_TOKEN or AUTH_PASSPHRASE in GitHub. Set those on the Worker; they persist across deploys.

If you already deploy with Workers Builds, this workflow is redundant. Delete it.

Writes

Set YNAB_ALLOW_WRITES to "true" in wrangler.jsonc and redeploy. Then disconnect and reconnect the connector in Claude, because the granted scope lives on the existing token.

Connect in Claude

Settings → Connectors → Add custom connector:

https://your-worker-url.workers.dev/mcp

The /mcp path is required. Leave the OAuth client id and secret empty; Claude registers itself. Type your passphrase on the consent screen.

The Worker must be reachable from Anthropic’s egress range 160.79.104.0/21. Workers are public by default, so this only matters if you put Cloudflare Access or a WAF in front of it.

Local development

cp .dev.vars.example .dev.vars   # fill in the two secrets
npx wrangler dev

Local KV is simulated, so the committed namespace id is fine here. Claude cannot reach localhost.

Against a deployed Worker:

node scripts/smoke-test.mjs https://your-worker-url.workers.dev 'your-passphrase'
node scripts/check-behaviors.mjs https://your-worker-url.workers.dev 'your-passphrase'

npm test checks transfer handling, payee merge, and advertised tool schemas. It does not need a live Worker.

Configuration

Set in wrangler.jsonc under vars:

Set with npx wrangler secret put, never in the repo:

Security

• The passphrase is hashed and compared in constant time. The consent page has a strict CSP, X-Frame-Options: DENY, and no JavaScript.

• Rotating YNAB_ACCESS_TOKEN is invisible to Claude. Rotating AUTH_PASSPHRASE does not drop existing connections. If the passphrase leaked, change it and clear the OAUTH_KV namespace, then reconnect.

• Cloudflare’s OAuth provider keeps the previous refresh token valid for one rotation, so a lost in-flight response does not lock Claude out. A token older than that one step is rejected.

License

MIT