Lets an AI assistant read and modify your YNAB budget plans and transactions.
Also known as calebl/ynab-mcp-server
- Stars
- 169
- Tools
- 23
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is YNAB MCP?
YNAB lets an AI assistant read and modify your YNAB budget plans and transactions. It exposes 23 tools, such as ynab_list_plans, ynab_plan_summary, ynab_list_accounts.
Summary generated from the project's README
About YNAB MCP server
Managing personal finances through an AI assistant is possible with this server, which connects to your YNAB account to read and modify budget plans and transactions. It is designed for individuals who want to interact with their financial data using natural language via clients like Claude Desktop, Claude Code, or the Claude mobile app. Users must provide a YNAB Personal Access Token as an environment variable, which remains private and is never shared with the language model.
Developers can deploy this in two ways: locally via stdio for use on a single machine, or remotely using a Cloudflare Worker. The remote deployment allows for access from the web and mobile apps even when your computer is off, utilizing GitHub sign-in for security. The server includes specialized tools like ynab_list_plans and ynab_plan_summary to provide financial insights, and it can be configured in a read-only mode to prevent any accidental changes to your budget.
What you can do with it
- 1Monitor spending via remote deploymentAccess your budget data from a mobile device by deploying the server to a Cloudflare Worker.
- 2Enable safe read-only accessConfigure the server to allow the AI to view your finances without the ability to create or delete transactions.
Written from the project's README. Every use case is checked against a quote from it.
YNAB MCP tools 23
Detected from the READMEynab_list_plansynab_plan_summaryynab_list_accountsynab_list_categoriesynab_list_payeesynab_list_monthsynab_list_scheduled_transactionsynab_get_transactionsynab_suggest_categoriesynab_spending_by_categoryynab_spending_by_payeeynab_cash_flow
Show all 23 toolsShow fewer tools
ynab_balance_forecastynab_detect_recurringynab_create_transactionynab_update_transactionynab_delete_transactionynab_bulk_approve_transactionsynab_apply_category_suggestionsynab_update_category_budgetynab_import_transactionsynab_move_moneyynab_auto_assign
Configuration
YNAB_API_TOKENYNAB_PLAN_ID
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubynab-mcp-server
A Model Context Protocol (MCP) server for interacting with your YNAB plans at https://ynab.com
In order to have an AI interact with this tool, you will need to get your Personal Access Token from YNAB: https://api.ynab.com/#personal-access-tokens. When adding this MCP server to any client, you will need to provide your personal access token as YNAB_API_TOKEN. This token is never directly sent to the LLM. It is stored privately in an environment variable for use with the YNAB api.
A Model Context Protocol server that lets an AI assistant read and modify a YNAB plan.
The server talks to the YNAB API through the official
ynab SDK. Your Personal Access Token
lives in an environment variable and is never sent to the model.
It runs two ways from one codebase:
- Local (stdio) — a child process of Claude Code or Claude Desktop on your own machine. Simplest, but only works on that machine while it is running.
- Remote (Cloudflare Worker) — deployed behind GitHub sign-in and added to claude.ai as a custom connector, so it works from the web and the mobile app with your computer switched off. See DEPLOY.md.
Both entry points register the shared tools from src/registry.ts. The Worker
can also run an optional scheduled auto-budget service that records what it
would categorize, approve and assign without changing your plan and delivers
spending alerts; see
Auto-budget service.
Other providers:
Setup
Get a Personal Access Token from https://api.ynab.com/#personal-access-tokens, then:
npm install
npm run build
Environment variables:
| Variable | Required | Purpose |
|---|---|---|
YNAB_API_TOKEN |
yes | Personal Access Token used for every API call |
YNAB_PLAN_ID |
no | Default plan, so tools can omit planId. Find it with ynab_list_plans. |
TYPESAFE_API_KEY |
no | Operator-owned TypeSafe credential. Required, but not sufficient, to enable category suggestions. |
YNAB_AI_CATEGORIZATION |
no | Set to "true" together with TYPESAFE_API_KEY to expose the opt-in suggestion tool. |
YNAB_AI_TYPICAL_PAYEES |
no | Set to "true" to send each category's most frequent payee names from the last 12 months with each model request. Off by default because it discloses aggregated payee history to TypeSafe. |
YNAB_READ_ONLY |
no | Set to "true" (case-insensitive; surrounding whitespace is ignored) to remove tools that write to YNAB, in the stdio server, the HTTP server and the Worker. |
YNAB_MCP_HOST, PORT |
no | HTTP server only. Address and port to listen on; default 127.0.0.1 and 3000. |
YNAB_MCP_ALLOWED_ORIGINS |
no | HTTP server only. Comma-separated browser origins allowed to call /mcp (e.g. https://app.example.com). Each entry is reduced to scheme, host and port, so a trailing slash is ignored. Empty by default, which refuses every request that carries an Origin header. |
YNAB_MCP_ALLOWED_HOSTS |
no | HTTP server only. Comma-separated extra Host hostnames accepted while listening on a loopback address, for a reverse proxy on the same machine that forwards the client's Host (e.g. mcp.example.com). |
ALLOWED_GITHUB_LOGIN |
no | Worker only. The single GitHub login allowed through GitHub sign-in. Required for GitHub sign-in. |
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET |
no | Worker only. The GitHub OAuth app's credentials. Required for GitHub sign-in. |
ALLOWED_REDIRECT_URIS |
no | Worker only. Exact OAuth callback URIs that GitHub sign-in may deliver grants to. See Restricting redirects. Must be unset with Cloudflare Access. |
CF_ACCESS_TEAM_DOMAIN |
no | Worker only. Your Cloudflare Access team domain (<team>.cloudflareaccess.com). Setting any CF_ACCESS_* value replaces GitHub sign-in with Cloudflare Access, which needs all three. |
CF_ACCESS_AUD |
no | Worker only. The Access application's Audience (AUD) tag. |
CF_ACCESS_ALLOWED_EMAIL |
no | Worker only. The single email allowed through Access. Any other identity, including a service token, is refused. |
Local: Claude Desktop / Claude Code
{
"mcpServers": {
"ynab": {
"command": "node",
"args": ["/absolute/path/to/ynab-mcp-server/dist/index.js"],
"env": {
"YNAB_API_TOKEN": "your-token",
"YNAB_PLAN_ID": "your-plan-id"
}
}
}
}
Self-hosted: streamable HTTP
To run the server in a container or behind your own reverse proxy or MCP gateway, start the HTTP entry point instead of the stdio one.
It does no authentication of its own. Anyone who can reach
/mcpuses your YNAB token with every tool you expose, including the write tools unlessYNAB_READ_ONLYis set. It listens on127.0.0.1unless you setYNAB_MCP_HOST; only widen that on a private network or behind a proxy that authenticates callers. For a hosted endpoint with sign-in built in, use the Worker below.
On this machine only:
npm run build
YNAB_API_TOKEN=your-token npm run start:http
Outside a checkout, name the package as well as the command, so npm never
looks up a package called ynab-mcp-server-http:
YNAB_API_TOKEN=your-token npx --package ynab-mcp-server ynab-mcp-server-http
In a container, where it must listen on every interface, start read-only unless whatever sits in front of it authenticates callers:
YNAB_API_TOKEN=your-token YNAB_READ_ONLY=true YNAB_MCP_HOST=0.0.0.0 PORT=3000 node dist/http.js
It serves stateless streamable HTTP
at POST /mcp and a health check at GET /healthz, with the same tools and
environment variables as the stdio server. It holds one YNAB client for the
life of the process, so the plan-settings cache is shared across requests.
Bound to a non-loopback address with the write tools on, it prints a warning
at startup.
To stop a web page reaching it through DNS rebinding, /mcp refuses with a
403 any request that carries an Origin header not listed in
YNAB_MCP_ALLOWED_ORIGINS. Browsers always send Origin on a POST;
gateways and server-side MCP clients do not, so they are unaffected. While it
listens on a loopback address it also refuses any request whose Host is not
localhost, 127.0.0.1 or [::1].
A reverse proxy on the same machine usually forwards the client's Host
(Caddy and Traefik by default, nginx with proxy_set_header Host $host), which
that check refuses with 403 Host not allowed. Either have the proxy send the
upstream address as Host (Caddy: header_up Host {upstream_hostport};
nginx's default $proxy_host already does), or list the public hostname in
YNAB_MCP_ALLOWED_HOSTS.
Remote: phone and claude.ai
The stdio server above cannot be reached from a phone. To use these tools from
claude.ai or the Claude mobile app, deploy src/worker/ to Cloudflare Workers
and add it as a custom connector. DEPLOY.md has the full walk
through; the shape of it:
- Copy
wrangler.example.jsoncto the git-ignoredwrangler.jsonc, remove the optional placeholderAUTOBUDGET_DBblock unless you are configuring the auto-budget service, runnpx wrangler login, then create theOAUTH_KVnamespace npm run deployonce to learn your*.workers.devhostname- Create a GitHub OAuth app whose callback is
https://<host>/callback - Use
npx wrangler secret putforALLOWED_GITHUB_LOGIN,YNAB_API_TOKEN,GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET, andTYPESAFE_API_KEY - Run
npm run deployagain - Add
https://<host>/mcpas a custom connector in claude.ai
The YNAB token stays a Worker secret and never reaches the client. GitHub sign-in
controls who may connect to the remote Worker; the YNAB Personal Access
Token controls which YNAB account it reaches. They answer different
questions, and neither substitutes for the other. The Worker uses one
server-wide YNAB token, so anyone admitted through the GitHub gate reaches the
deployer's YNAB account, money, and every plan available to that token—not
their own YNAB account.
ynab_list_plans lists all of those plans, and a caller-supplied planId
overrides the optional YNAB_PLAN_ID default. Any GitHub account other than
ALLOWED_GITHUB_LOGIN is refused. This matters because the tool set can create
and delete transactions—an unauthenticated endpoint would grant access to those
plans to anyone who found the URL.
The Worker is not tied to Claude. Any MCP client that supports remote servers
with OAuth can connect, for example Claude (claude.ai, desktop, and mobile),
ChatGPT connectors, Claude Code, or the MCP Inspector. Because clients register
themselves, every permitted sign-in shows an approval page naming the client
and the exact address the grant will be sent to; approve only a sign-in you
just started. To restrict which clients can connect at all, set
ALLOWED_REDIRECT_URIS to their exact callback URIs (loopback redirects for
local clients stay allowed). See
Approving MCP clients for example callback
URIs.
To sign in through Cloudflare Access instead of GitHub, see Cloudflare Access, which also lists the MCP clients tested with it.
Why not YNAB OAuth?
YNAB OAuth is deliberately not supported. Its token exchange requires a client secret even with PKCE; an open-source package cannot ship a secret, so a local package cannot honestly implement the authorization-code flow (OAuth application requirements). The only secretless flow YNAB documents is the implicit grant, which expires in two hours with no refresh (OAuth application requirements). YNAB recommends a Personal Access Token for an individual accessing their own account (Personal Access Tokens).
Setting YNAB_READ_ONLY to "true" drops every YNAB write tool from the tool
list, which is worth considering for a connector you will mostly use on a phone.
Tools
Plan-scoped tools take an optional planId that falls back to
YNAB_PLAN_ID. Optional tool inputs may be null; the server treats null
the same as omitting that input. All monetary values — in both directions — are
plain currency amounts, never YNAB's milliunits. Reported amounts use the
plan currency's precision (three decimals for currencies such as the Kuwaiti
dinar) and fall back to two decimals if its settings cannot be read; conversion
happens in src/tools/money.ts.
Reading
| Tool | What it does |
|---|---|
ynab_list_plans |
Every plan on the account. Run this first to find a plan ID. |
ynab_plan_summary |
A month at a glance: income, budgeted, activity, Ready to Assign, plus categories split into overspent, underfunded (goal not yet met) and positive_balance. Hidden and deleted categories are excluded. budgetVsActuals: true adds a budget_vs_actuals block: budgeted, activity, balance, variance (budgeted plus activity) and percent_used (null when nothing was assigned) per category, subtotalled per category group and in totals. Credit Card Payments is listed as its own group but left out of totals, since its activity is card spending moving in minus payments going out. YNAB's internal Inflow: Ready to Assign category (whose activity is the month's income) is skipped; other internal categories, such as Uncategorized, are listed and counted when they have activity. |
ynab_list_accounts |
Accounts with balances. includeClosedAccounts to see closed ones. |
ynab_list_categories |
Categories grouped by category group, with goal info. |
ynab_list_payees |
Payees, for resolving payee IDs. |
ynab_list_months |
Every plan month since the plan began, with raw income, budgeted, activity, Ready to Assign, age-of-money and note fields. For recent income versus spending, use ynab_cash_flow. |
ynab_list_scheduled_transactions |
The scheduled transactions set up in YNAB. For recurring charges found in transaction history, see ynab_detect_recurring; for a projected balance, ynab_balance_forecast. |
ynab_get_transactions |
Transactions optionally filtered to sinceDate–untilDate, by type (all/uncategorized/unapproved), and by at most one of accountId, categoryId or payeeId (the first in that order wins). To search, add payeeContains, memoContains (case-insensitive), minAmount/maxAmount (ignoring sign) or direction (outflow/inflow/any); any search option or untilDate adds a totals block (count, inflow, outflow, net) over every match, including transfers between accounts, and totalsOnly: true returns only that. Without categoryId or payeeId, splits are matched leg by leg and the totals count only the matching legs; with them, rows are matched as YNAB returns them, so a split's parent row in the payee listing counts at its full amount. Rows come back newest first; limit defaults to 100, keeps the most recent rows, and does not affect the totals. |
ynab_suggest_categories |
Opt-in, read-only category previews for unapproved, uncategorized ordinary outflows. Deleted and categorized rows are dropped in default mode; approved, reconciled, balance-adjustment, transfer, split, and inflow rows are skipped as applicable. |
Category suggestions (optional)
ynab_apply_category_suggestions is a separate write tool that is available
without enabling the TypeSafe preview. Provide up to 25 explicit
transaction_id, category_id, and expected_content_fingerprint rows. The
tool refetches each transaction and rejects stale or ineligible changes; a retry
whose category is already applied is a no-op. It supports validation-only dry
runs and returns a pre-write undo manifest, but does not perform the undo. It
never auto-applies suggestions, calls TypeSafe, or approves transactions.
ynab_suggest_categories is off by default. To expose it, set both an
operator-owned TYPESAFE_API_KEY and YNAB_AI_CATEGORIZATION=true, then restart
the server. The API key is read from the environment (or a Worker secret), never
from a tool argument. Omit transactionIds, pass null, or pass an empty
array to fetch unapproved transactions and retain only uncategorized rows;
provide IDs to inspect only those transactions. In default mode, the tool
checks every retained row for deterministic eligibility and then applies
limit to the first eligible outflows in YNAB's returned order. Skipped rows
do not consume the limit.
The tool is a dry-run preview: it never writes to YNAB, approves a transaction,
or changes the behavior of ynab_update_transaction. It first handles exact
facts in code—dropping deleted rows and handling approved or reconciled rows,
YNAB balance adjustments, transfers, splits, inflows, existing categories, and
hidden/internal categories. In default mode, transactions contains only the
eligible rows inspected, transaction_count is that row count, and
eligible_transaction_count reports all eligible rows available before the
limit. The top-level skipped object reports total_count and a count plus
transaction_ids for each reason: skipped_approved, skipped_reconciled,
skipped_balance_adjustment, skipped_transfer, skipped_split,
skipped_inflow, and skipped_already_categorized. With explicit
transactionIds, every non-deleted fetched row remains an individual result,
including rows carrying a skipped_* status; deleted rows are omitted.
Payee history uses the latest 12 months, capped at 50 qualifying rows. When the
payee has no qualifying rows with the same payee ID, history falls back to rows
from payees with a similar name: after Unicode NFC normalization, lowercasing,
and removing everything except letters and numbers, one name begins the other
and the shorter is at least six characters, so a truncated bank payee such as
"Better Bl" draws on "Better Blend" history. Each history summary reports
match (payee, similar_payee_name, or null) and
matched_payee_names.
Each eligible row is then routed in this order, and source names the step
that answered:
- Exact-payee history (
history_rule). When at least one qualifying row has the same payee ID and every such row uses the same still-eligible category, that category issuggested. When those rows disagree, the row isneeds_reviewand proposes the most recently used category, with the others astop_alternativescarrying theirhistory_count. No model call is made for either case. - Personal prior (
personal_prior). A naive-Bayes classifier is trained for each request on the plan's own categorized ordinary outflows from the same 12-month history, using payee and bank-import name tokens, the account, and a coarse amount bucket. It is used when history contains categorized rows across at least two categories; a single-category prior cannot rank alternatives. Name tokens never seen in training are ignored rather than scored. When its top category reaches probability 0.9, the row issuggestedwithout a model call. The probability is reported underpersonal_prior.ranking, never asmodel_confidence. Below 0.9 the prior only ranks: its top three appear on the model's row for comparison. - Model (
jev). Every remaining row goes to TypeSafe's pinnedjev-1.13.0System One model in batches of ten. A model answer is a ranked shortlist, never a suggestion: every answer that names a category isneeds_review, while an explicit model abstention isleft_uncategorized. The pinned model's stored review threshold is therefore 0; thresholds stay model-specific because confidence scales differ between models.
Similar-name history is never a rule; when a row reaches the model, it is
included as suggestive evidence. The history summary's reference_category_id is the category a
proposal is compared with: the most recently used one for exact-payee history,
and the plurality for similar-name history. A similar-name disagreement is
reported as conflict but does not change the status, because a prefix match
does not establish merchant identity. Every inspected eligible row includes a
status, source, content fingerprint, proposed category, model confidence and
winning probability (model rows only), up to three alternatives, the history
summary, and the personal-prior ranking where one was computed. The response's
thresholds object reports the values in force, and personal_prior reports
how many rows trained the prior and whether it was available for routing.
Applying a suggestion remains a separate, explicit human decision using
ynab_apply_category_suggestions (or the general ynab_update_transaction
tool).
Why this order: households file payees their own way, such as restaurants under a groceries category or clinics under a savings category. A general-purpose model cannot know that, but the plan's own history encodes it. On real household history, history rules and the personal prior were much more accurate than a model on the same rows. The model's high-confidence answers were wrong far more often than on synthetic fixtures, which is why they are review-only. To evaluate your own plan, or a local model, see Evaluating categorization and local decision models.
Enabling this feature sends the transaction's display payee, imported/original
payee, memo, amount, date, and account name/type/on-budget status, plus visible
category group and category names, to TypeSafe as a third-party processor.
For model-bound rows with similar-name matches, it also sends the matched payee
names and per-category key, group, name, and count. When
YNAB_AI_TYPICAL_PAYEES=true, each model request also lists up to eight of each
category's most frequent payee names from the last 12 months
(typical_payees), and the response sets
typical_payees_sent: true. This makes the model noticeably more accurate on a
household's own filing habits, but it discloses aggregated payee history, so it
is off by default. It does not send YNAB UUIDs, balances, goals,
approval/cleared state, or raw transaction history. Rows answered by history or
the personal prior are never sent. TypeSafe's published
Jev 1.13 price at the time of this release is $0.042 per million input tokens;
output tokens are free. The tool returns preflight estimates, actual token
usage, and projected cost on each run
and refuses requests over its per-call token/cost ceilings. Pricing and
provider limits can change; check https://docs.typesafe.ai/models.
The prototype is intentionally narrow and not default-on. Its original 98.3% exact-label, 98.9% top-three, and 60/60 expected-abstention results came from 40 synthetic, single-evaluator fixtures, not a production accuracy claim. Real household history is much harder, as described above.
YNAB MCP questions
What tools does YNAB MCP provide?
It exposes 23 tools, including ynab_list_plans, ynab_plan_summary, ynab_list_accounts, ynab_list_categories, ynab_list_payees.
How do I authorize the server to access my YNAB account?
You need to provide a Personal Access Token from YNAB as the YNAB_API_TOKEN environment variable.
Is my YNAB API token safe from the LLM?
Yes, the token is stored privately in an environment variable and is never sent directly to the model.
How can I use YNAB tools on my mobile phone via Claude?
You can deploy the server to Cloudflare Workers and add it as a custom connector in claude.ai to enable access from the web and mobile app.