Skip to content
Back to search

ynab-mcp-server

Model Context Protocol for YNAB (you need a budget)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/calebl/ynab-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/calebl/ynab-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/calebl--ynab-mcp-server/badge.svg)](/listings/calebl--ynab-mcp-server)

HTML

<a href="/listings/calebl--ynab-mcp-server"><img src="/api/listings/calebl--ynab-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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. |

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"
      }
    }
  }
}

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](./DEPLOY.md) has the full walk through; the shape of it:

1. Copy `wrangler.example.jsonc` to the git-ignored `wrangler.jsonc`, run `npx wrangler login`, then create the `OAUTH_KV` namespace 2. `npm run deploy` once to learn your `*.workers.dev` hostname 3. Create a GitHub OAuth app whose callback is `https://<host>/callback` 4. Use `npx wrangler secret put` for `ALLOWED_GITHUB_LOGIN`, `YNAB_API_TOKEN`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, and `TYPESAFE_API_KEY` 5. Run `npm run deploy` again 6. Add `https://<host>/mcp` as 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](./DEPLOY.md#approving-mcp-clients) for example callback URIs.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 517 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # ynab-mcp-server
  2. A Model Context Protocol (MCP) server for interacting with your YNAB plans at https://ynab.com
  3. In order to have an AI interact with this tool, you will need to get your Personal Access Token
  4. from YNAB: https://api.ynab.com/#personal-access-tokens. When adding this MCP server to any
  5. client, you will need to provide your personal access token as YNAB_API_TOKEN. **This token
  6. is never directly sent to the LLM.** It is stored privately in an environment variable for
  7. use with the YNAB api.
  8. A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an AI
  9. assistant read and modify a [YNAB](https://ynab.com) plan.
  10. The server talks to the YNAB API through the official
  11. [`ynab` SDK](https://github.com/ynab/ynab-sdk-js). Your Personal Access Token
  12. lives in an environment variable and is never sent to the model.
  13. It runs two ways from one codebase:
  14. - **Local (stdio)** — a child process of Claude Code or Claude Desktop on your
  15. own machine. Simplest, but only works on that machine while it is running.
  16. - **Remote (Cloudflare Worker)** — deployed behind a sign-in of your choice,
  17. Cloudflare Access or GitHub, and added to any MCP client that supports remote
  18. servers, such as claude.ai as a custom connector, so it works from the web
  19. and your phone with your computer switched off. See [DEPLOY.md](./DEPLOY.md).
  20. Both entry points register the shared tools from `src/registry.ts`. The Worker
  21. can also run an optional scheduled auto-budget service that records what it
  22. would categorize, approve and assign without changing your plan and delivers
  23. spending alerts; see
  24. [Auto-budget service](./DEPLOY.md#auto-budget-service-optional).
  25. Other providers:
  26. <a href="https://glama.ai/mcp/servers/@calebl/ynab-mcp-server">
  27. <img width="380" height="200" src="https://glama.ai/mcp/servers/@calebl/ynab-mcp-server/badge" alt="YNAB Server MCP server" />
  28. </a>
  29. [![LightNow](https://lightnow.ai/badge/io.github.calebl/ynab-mcp-server)](https://lightnow.ai/servers/io.github.calebl/ynab-mcp-server)
  30. ## Setup
  31. Get a Personal Access Token from <https://api.ynab.com/#personal-access-tokens>, then:
  32. ```bash
  33. npm install
  34. npm run build
  35. ```
  36. Environment variables:
  37. | Variable | Required | Purpose |
  38. | --- | --- | --- |
  39. | `YNAB_API_TOKEN` | yes | Personal Access Token used for every API call |
  40. | `YNAB_PLAN_ID` | no | Default plan, so tools can omit `planId`. Find it with `ynab_list_plans`. |
  41. | `TYPESAFE_API_KEY` | no | Operator-owned TypeSafe credential. Required, but not sufficient, to enable category suggestions. |
  42. | `YNAB_AI_CATEGORIZATION` | no | Set to `"true"` together with `TYPESAFE_API_KEY` to expose the opt-in suggestion tool. |
  43. | `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. |
  44. | `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. |
  45. | `YNAB_MCP_HOST`, `PORT` | no | HTTP server only. Address and port to listen on; default `127.0.0.1` and `3000`. |
  46. | `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. |
  47. | `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`). |
  48. | `ALLOWED_GITHUB_LOGIN` | no | Worker only. The single GitHub login allowed through [GitHub sign-in](./DEPLOY.md#github-sign-in). Required for GitHub sign-in. |
  49. | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | no | Worker only. The GitHub OAuth app's credentials. Required for GitHub sign-in. |
  50. | `ALLOWED_REDIRECT_URIS` | no | Worker only. Exact OAuth callback URIs that GitHub sign-in may deliver grants to. See [Restricting redirects](./DEPLOY.md#restricting-redirects-optional). Must be unset with Cloudflare Access. |
  51. | `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](./DEPLOY.md#cloudflare-access), which needs all three. |
  52. | `CF_ACCESS_AUD` | no | Worker only. The Access application's Audience (AUD) tag. |
  53. | `CF_ACCESS_ALLOWED_EMAIL` | no | Worker only. The single email allowed through Access. Any other identity, including a service token, is refused. |
  54. ### Local: Claude Desktop / Claude Code
  55. ```json
  56. {
  57. "mcpServers": {
  58. "ynab": {
  59. "command": "node",
  60. "args": ["/absolute/path/to/ynab-mcp-server/dist/index.js"],
  61. "env": {
  62. "YNAB_API_TOKEN": "your-token",
  63. "YNAB_PLAN_ID": "your-plan-id"
  64. }
  65. }
  66. }
  67. }
  68. ```
  69. ### Self-hosted: streamable HTTP
  70. To run the server in a container or behind your own reverse proxy or MCP
  71. gateway, start the HTTP entry point instead of the stdio one.
  72. > **It does no authentication of its own.** Anyone who can reach `/mcp` uses
  73. > your YNAB token with every tool you expose, including the write tools
  74. > unless `YNAB_READ_ONLY` is set. It listens on `127.0.0.1` unless you set
  75. > `YNAB_MCP_HOST`; only widen that on a private network or behind a proxy
  76. > that authenticates callers. For a hosted endpoint with sign-in built in,
  77. > use the Worker below.
  78. On this machine only:
  79. ```sh
  80. npm run build
  81. YNAB_API_TOKEN=your-token npm run start:http
  82. ```
  83. Outside a checkout, name the package as well as the command, so npm never
  84. looks up a package called `ynab-mcp-server-http`:
  85. ```sh
  86. YNAB_API_TOKEN=your-token npx --package ynab-mcp-server ynab-mcp-server-http
  87. ```
  88. In a container, where it must listen on every interface, start read-only
  89. unless whatever sits in front of it authenticates callers:
  90. ```sh
  91. YNAB_API_TOKEN=your-token YNAB_READ_ONLY=true YNAB_MCP_HOST=0.0.0.0 PORT=3000 node dist/http.js
  92. ```
  93. It serves stateless [streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http)
  94. at `POST /mcp` and a health check at `GET /healthz`, with the same tools and
  95. environment variables as the stdio server. It holds one YNAB client for the
  96. life of the process, so the plan-settings cache is shared across requests.
  97. Bound to a non-loopback address with the write tools on, it prints a warning
  98. at startup.
  99. To stop a web page reaching it through DNS rebinding, `/mcp` refuses with a
  100. 403 any request that carries an `Origin` header not listed in
  101. `YNAB_MCP_ALLOWED_ORIGINS`. Browsers always send `Origin` on a POST;
  102. gateways and server-side MCP clients do not, so they are unaffected. While it
  103. listens on a loopback address it also refuses any request whose `Host` is not
  104. `localhost`, `127.0.0.1` or `[::1]`.
  105. A reverse proxy on the same machine usually forwards the client's `Host`
  106. (Caddy and Traefik by default, nginx with `proxy_set_header Host $host`), which
  107. that check refuses with `403 Host not allowed`. Either have the proxy send the
  108. upstream address as `Host` (Caddy: `header_up Host {upstream_hostport}`;
  109. nginx's default `$proxy_host` already does), or list the public hostname in
  110. `YNAB_MCP_ALLOWED_HOSTS`.
  111. ### Remote: Cloudflare Worker
  112. The stdio server above cannot be reached from a phone. To use these tools from
  113. claude.ai, the Claude mobile app, or another MCP client that supports remote
  114. servers, deploy `src/worker/` to Cloudflare Workers and add its `/mcp` URL to
  115. the client. The Worker is not tied to Claude. [DEPLOY.md](./DEPLOY.md) has the
  116. full walk through; the shape of it:
  117. 1. Copy `wrangler.example.jsonc` to the git-ignored `wrangler.jsonc`, remove
  118. the optional placeholder `AUTOBUDGET_DB` block unless you are configuring
  119. the [auto-budget service](./DEPLOY.md#auto-budget-service-optional), and
  120. run `npx wrangler login`
  121. 2. Set up one of the two sign-ins below
  122. 3. Use `npx wrangler secret put` for `YNAB_API_TOKEN`, and optionally
  123. `YNAB_PLAN_ID`. `TYPESAFE_API_KEY` is optional too, needed only for
  124. [category suggestions](./DEPLOY.md#3-set-deployment-values-and-secrets)
  125. 4. Run `npm run deploy`
  126. 5. Add `https://<host>/mcp` to your MCP client, for example as a custom
  127. connector in claude.ai, and complete the sign-in it opens
  128. #### Sign-in: Cloudflare Access
  129. For a Cloudflare account that uses Access. Access signs the client in at
  130. Cloudflare's edge, so no GitHub OAuth app or `OAUTH_KV` namespace is needed.
  131. Full steps: [Cloudflare Access](./DEPLOY.md#cloudflare-access).
  132. 1. Remove the `kv_namespaces` block from `wrangler.jsonc`, and deploy once
  133. so the Worker exists
  134. 2. Create an Access application for the Worker with an Allow policy for your
  135. email and Managed OAuth on, listing each client's callback URI, with
  136. `npm run cf-access` ([setup script](./DEPLOY.md#setup-script)) or in the
  137. dashboard
  138. 3. Use `npx wrangler secret put` for `CF_ACCESS_TEAM_DOMAIN`, `CF_ACCESS_AUD`,
  139. and `CF_ACCESS_ALLOWED_EMAIL`, and leave `ALLOWED_REDIRECT_URIS` unset
  140. #### Sign-in: GitHub
  141. The Worker runs its own OAuth flow with GitHub as the identity provider.
  142. Full steps: [GitHub sign-in](./DEPLOY.md#github-sign-in).
  143. 1. Create the `OAUTH_KV` namespace and put its ID in `wrangler.jsonc`
  144. 2. `npm run deploy` once to learn your `*.workers.dev` hostname
  145. 3. Create a GitHub OAuth app whose callback is `https://<host>/callback`
  146. 4. Use `npx wrangler secret put` for `ALLOWED_GITHUB_LOGIN`,
  147. `GITHUB_CLIENT_ID`, and `GITHUB_CLIENT_SECRET`
  148. #### Who may connect
  149. The YNAB token stays a Worker secret and never reaches the client. The sign-in
  150. controls **who may connect** to the remote Worker; the YNAB Personal Access
  151. Token controls **which YNAB account it reaches**. They answer different
  152. questions, and neither substitutes for the other. The Worker uses one
  153. server-wide YNAB token, so anyone admitted through the sign-in reaches the
  154. deployer's YNAB account, money, and every plan available to that token—not
  155. their own YNAB account.
  156. `ynab_list_plans` lists all of those plans, and a caller-supplied `planId`
  157. overrides the optional `YNAB_PLAN_ID` default. This matters because the tool
  158. set can create and delete transactions—an unauthenticated endpoint would grant
  159. access to those plans to anyone who found the URL. Each sign-in admits one
  160. account:
  161. - **Cloudflare Access** admits only `CF_ACCESS_ALLOWED_EMAIL`; the Access
  162. application's allowed redirect URIs decide which clients can connect. See
  163. [Cloudflare Access](./DEPLOY.md#cloudflare-access) for its configuration and
  164. client compatibility notes.
  165. - **GitHub** admits only `ALLOWED_GITHUB_LOGIN`. Each sign-in shows an approval
  166. page naming the client and callback address, and `ALLOWED_REDIRECT_URIS` can
  167. restrict clients to exact callbacks. See
  168. [Approving MCP clients](./DEPLOY.md#approving-mcp-clients).
  169. Any MCP client that supports remote servers with OAuth can connect, for
  170. example Claude, ChatGPT connectors, Claude Code, or the MCP Inspector.
  171. ## Why not YNAB OAuth?
  172. YNAB OAuth is deliberately not supported. Its token exchange requires a client
  173. secret even with PKCE; an open-source package cannot ship a secret, so a local
  174. package cannot honestly implement the authorization-code flow
  175. ([OAuth application requirements](https://api.ynab.com/#oauth-applications)).
  176. The only secretless flow YNAB documents is the implicit grant, which expires in
  177. two hours with no refresh
  178. ([OAuth application requirements](https://api.ynab.com/#oauth-applications)).
  179. YNAB recommends a Personal Access Token for an individual accessing their own
  180. account
  181. ([Personal Access Tokens](https://api.ynab.com/#personal-access-tokens)).
  182. Setting `YNAB_READ_ONLY` to `"true"` drops every YNAB write tool from the tool
  183. list, which is worth considering for a connector you will mostly use on a phone.
  184. ## Tools
  185. Plan-scoped tools take an optional `planId` that falls back to
  186. `YNAB_PLAN_ID`. Optional tool inputs may be `null`; the server treats `null`
  187. the same as omitting that input. All monetary values — in both directions — are
  188. plain currency amounts, never YNAB's milliunits. Reported amounts use the
  189. plan currency's precision (three decimals for currencies such as the Kuwaiti
  190. dinar) and fall back to two decimals if its settings cannot be read; conversion
  191. happens in `src/tools/money.ts`.
  192. ### Reading
  193. | Tool | What it does |
  194. | --- | --- |
  195. | `ynab_list_plans` | Every plan on the account. Run this first to find a plan ID. |
  196. | `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. |
  197. | `ynab_list_accounts` | Accounts with balances. `includeClosedAccounts` to see closed ones. |
  198. | `ynab_list_categories` | Categories grouped by category group, with goal info. |
  199. | `ynab_list_payees` | Payees, for resolving payee IDs. |
  200. | `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`. |
  201. | `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`. |
  202. | `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. Imported rows also carry `import_payee_name` (YNAB's cleaned-up payee) and `import_payee_name_original` (the bank's raw text). Rows come back newest first; `limit` defaults to 100, keeps the most recent rows, and does not affect the totals. |
  203. | `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. |
  204. ### Category suggestions (optional)
  205. `ynab_apply_category_suggestions` is a separate write tool that is available
  206. without enabling the TypeSafe preview. Provide up to 25 explicit
  207. `transaction_id`, `category_id`, and `expected_content_fingerprint` rows. The
  208. tool refetches each transaction and rejects stale or ineligible changes; a retry
  209. whose category is already applied is a no-op. It supports validation-only dry
  210. runs and returns a pre-write undo manifest, but does not perform the undo. It
  211. never auto-applies suggestions, calls TypeSafe, or approves transactions.
  212. `ynab_suggest_categories` is off by default. To expose it, set both an
  213. operator-owned `TYPESAFE_API_KEY` and `YNAB_AI_CATEGORIZATION=true`, then restart
  214. the server. The API key is read from the environment (or a Worker secret), never
  215. from a tool argument. Omit `transactionIds`, pass `null`, or pass an empty
  216. array to fetch unapproved transactions and retain only uncategorized rows;
  217. provide IDs to inspect only those transactions. In default mode, the tool
  218. checks every retained row for deterministic eligibility and then applies
  219. `limit` to the first eligible outflows in YNAB's returned order. Skipped rows
  220. do not consume the limit.
  221. The tool is a dry-run preview: it never writes to YNAB, approves a transaction,
  222. or changes the behavior of `ynab_update_transaction`. It first handles exact
  223. facts in code—dropping deleted rows and handling approved or reconciled rows,
  224. YNAB balance adjustments, transfers, splits, inflows, existing categories, and
  225. hidden/internal categories. In default mode, `transactions` contains only the
  226. eligible rows inspected, `transaction_count` is that row count, and
  227. `eligible_transaction_count` reports all eligible rows available before the
  228. limit. The top-level `skipped` object reports `total_count` and a `count` plus
  229. `transaction_ids` for each reason: `skipped_approved`, `skipped_reconciled`,
  230. `skipped_balance_adjustment`, `skipped_transfer`, `skipped_split`,
  231. `skipped_inflow`, and `skipped_already_categorized`. With explicit
  232. `transactionIds`, every non-deleted fetched row remains an individual result,
  233. including rows carrying a `skipped_*` status; deleted rows are omitted.
  234. Payee history uses the latest 12 months, capped at 50 qualifying rows. When the
  235. payee has no qualifying rows with the same payee ID, history falls back to rows
  236. from payees with a similar name: after Unicode NFC normalization, lowercasing,
  237. and removing everything except letters and numbers, one name begins the other
  238. and the shorter is at least six characters, so a truncated bank payee such as
  239. "Better Bl" draws on "Better Blend" history. Each history summary reports
  240. `match` (`payee`, `similar_payee_name`, or `null`) and
  241. `matched_payee_names`.
  242. Each eligible row is then routed in this order, and `source` names the step
  243. that answered:
  244. 1. **Exact-payee history (`history_rule`).** When at least one qualifying row
  245. has the same payee ID and every such row uses the same still-eligible
  246. category, that category is `suggested`. When those rows disagree, the row is
  247. `needs_review` and proposes the most recently used category, with the
  248. others as `top_alternatives` carrying their `history_count`. No model call is
  249. made for either case.
  250. 2. **Personal prior (`personal_prior`).** A naive-Bayes classifier is trained
  251. for each request on the plan's own categorized ordinary outflows from the
  252. same 12-month history, using payee and bank-import name tokens, the account,
  253. and a coarse amount bucket. It is used when history contains categorized
  254. rows across at least two categories; a single-category prior cannot rank
  255. alternatives. Name tokens never seen in training are ignored rather than
  256. scored. When its top category reaches probability 0.9, the row is
  257. `suggested` without a model call. The probability is reported under
  258. `personal_prior.ranking`, never as `model_confidence`. Below 0.9 the prior
  259. only ranks: its top three appear on the model's row for comparison.
  260. 3. **Model (`jev`).** Every remaining row goes to TypeSafe's pinned
  261. `jev-1.13.0` System One model in batches of ten. A model answer is a ranked
  262. shortlist, never a suggestion: every answer that names a category is
  263. `needs_review`, while an explicit model abstention is `left_uncategorized`.
  264. The pinned model's stored review threshold is therefore 0; thresholds stay
  265. model-specific because confidence scales differ between models.
  266. Similar-name history is never a rule; when a row reaches the model, it is
  267. included as suggestive evidence. The history summary's `reference_category_id` is the category a
  268. proposal is compared with: the most recently used one for exact-payee history,
  269. and the plurality for similar-name history. A similar-name disagreement is
  270. reported as `conflict` but does not change the status, because a prefix match
  271. does not establish merchant identity. Every inspected eligible row includes a
  272. status, source, content fingerprint, proposed category, model confidence and
  273. winning probability (model rows only), up to three alternatives, the history
  274. summary, and the personal-prior ranking where one was computed. The response's
  275. `thresholds` object reports the values in force, and `personal_prior` reports
  276. how many rows trained the prior and whether it was available for routing.
  277. Applying a suggestion remains a separate, explicit human decision using
  278. `ynab_apply_category_suggestions` (or the general `ynab_update_transaction`
  279. tool).
  280. Why this order: households file payees their own way, such as restaurants
  281. under a groceries category or clinics under a savings category. A
  282. general-purpose model cannot know that, but the plan's own history encodes it.
  283. On real household history, history rules and the personal prior were much more
  284. accurate than a model on the same rows. The model's high-confidence answers
  285. were wrong far more often than on synthetic fixtures, which is why they are
  286. review-only. To evaluate your own plan, or a local model, see
  287. [Evaluating categorization and local decision models](./docs/local-decision-model.md).
  288. Enabling this feature sends the transaction's display payee, imported/original
  289. payee, memo, amount, date, and account name/type/on-budget status, plus visible
  290. category group and category names, to **TypeSafe as a third-party processor**.
  291. For model-bound rows with similar-name matches, it also sends the matched payee
  292. names and per-category key, group, name, and count. When
  293. `YNAB_AI_TYPICAL_PAYEES=true`, each model request also lists up to eight of each
  294. category's most frequent payee names from the last 12 months
  295. (`typical_payees`), and the response sets
  296. `typical_payees_sent: true`. This makes the model noticeably more accurate on a
  297. household's own filing habits, but it discloses aggregated payee history, so it
  298. is off by default. It does not send YNAB UUIDs, balances, goals,
  299. approval/cleared state, or raw transaction history. Rows answered by history or
  300. the personal prior are never sent. TypeSafe's published
  301. Jev 1.13 price at the time of this release is **$0.042 per million input tokens;
  302. output tokens are free**. The tool returns preflight estimates, actual token
  303. usage, and projected cost on each run
  304. and refuses requests over its per-call token/cost ceilings. Pricing and
  305. provider limits can change; check <https://docs.typesafe.ai/models>.
  306. The prototype is intentionally narrow and not default-on. Its original
  307. 98.3% exact-label, 98.9% top-three, and 60/60 expected-abstention results came
  308. from 40 synthetic, single-evaluator fixtures, not a production accuracy claim.
  309. Real household history is much harder, as described above.
  310. ### Reporting
  311. In the spending reports, splits are counted through their subtransactions and
  312. transfers between your own accounts are excluded, so they report spending rather
  313. than money movement.
  314. | Tool | What it does |
  315. | --- | --- |
  316. | `ynab_spending_by_category` | Total spend per category over a date range, biggest first, with share of total. Defaults to the last 30 days. With `monthly: true`, each category also gets spend per calendar month, its mean over the full months, and its last full month's change against the earlier full months, over the last `months` months (default 6, at most 24) or from `sinceDate`, which overrides `months`; `untilDate` then defaults to today. Totals are gross outflows, so refunds aren't netted. |
  317. | `ynab_spending_by_payee` | The same, grouped by merchant, including `monthly`. |
  318. | `ynab_cash_flow` | Income vs spending per month with the running net, from YNAB's own monthly totals. Defaults to the last 6 months. |
  319. | `ynab_balance_forecast` | The combined balance of your accounts over the next `days` (default 30, max 365, from today in UTC), projected from scheduled transactions only: starting balance, the scheduled events, the end-of-day running balance, the lowest point and the ending balance. `accountIds` picks the accounts; the default is every open on-budget account. `limit` caps the events (default 100, `0` leaves them out); `event_count`, the running balance, low point and ending balance always cover every event. Transfers between two included accounts (credit card payments too) net to zero; a transfer to an account outside the forecast counts as money leaving, and one from such an account as money arriving. Splits are counted leg by leg. Occurrences whose date has passed but that YNAB hasn't entered yet count on the first day, marked `overdue` with their `scheduled_date` and summarised in `overdue_schedules`. A twice-a-month schedule's second date is approximated as 15 days after the first when YNAB doesn't give it, and marked `approximate`. |
  320. | `ynab_detect_recurring` | Recurring outflows such as subscriptions and bills: a payee's charges of a similar amount at a regular interval (weekly to yearly), with typical amount, yearly cost at the latest amount, next expected date, whether it seems to have stopped, and whether a scheduled transaction has the same payee name. Loan and mortgage payments are transfers, so they are not included, and refunds are not netted. A heuristic; defaults to the last 365 days. |
  321. ### Writing
  322. | Tool | What it does |
  323. | --- | --- |
  324. | `ynab_create_transaction` | Creates a transaction. Needs `date`, `amount`, an account (`accountId` or `accountName`) and a payee (`payeeId` or `payeeName`); category optional as `categoryId` or `categoryName`, or `subtransactions` to split it. |
  325. | `ynab_update_transaction` | Updates any subset of an existing transaction's fields, or splits an unsplit one with `subtransactions`. |
  326. | `ynab_delete_transaction` | Deletes a transaction. Not undoable. |
  327. | `ynab_manage_scheduled_transaction` | Creates, updates or deletes a scheduled transaction with `action`. Create needs `date`, `amount` and an account (`accountId` or `accountName`), with optional `frequency` (default `never`), payee, category, `memo` and `flagColor`; update needs `scheduledTransactionId` and changes only the fields given; delete needs `scheduledTransactionId` and is not undoable. YNAB only accepts a date in the future, at most 5 years ahead, and does not support split scheduled transactions here. |
  328. | `ynab_bulk_approve_transactions` | Approves an array of transaction IDs in one API call, or un-approves them with `approved: false`. |
  329. | `ynab_apply_category_suggestions` | Applies up to 25 explicit category suggestions with refetch and stale-data checks, dry-run support, and a pre-write undo manifest. Never auto-applies or approves transactions. |
  330. | `ynab_update_category_budget` | Sets the total budgeted amount for one category in a month. Not an increment; use `ynab_move_money` to move money between categories. |
  331. | `ynab_import_transactions` | Triggers an import from linked institutions, the same as hitting Import in the YNAB app. |
  332. | `ynab_move_money` | Moves budgeted money between two categories in a month, for covering overspending. |
  333. | `ynab_auto_assign` | Spreads Ready to Assign over categories with unmet monthly goals, largest shortfall first. `dryRun` to preview, `maxTotal` to cap it. |
  334. #### Names instead of IDs
  335. `ynab_create_transaction` and `ynab_manage_scheduled_transaction` accept
  336. `accountName` and `categoryName` and match them loosely against the plan, so
  337. "ally checking" finds *Ally Checking*. Closed accounts and hidden categories are
  338. never matched. If a name is ambiguous or unrecognised the call fails and names
  339. the near misses rather than guessing, and successful calls echo back
  340. `matchedAccount` / `matchedCategory` so a wrong guess is visible.
  341. #### Split transactions
  342. `ynab_create_transaction` and `ynab_update_transaction` split a transaction
  343. across categories when given `subtransactions`: two or more entries of
  344. `{ amount, category_name, payee_name, memo }`, the same shape
  345. `ynab_get_transactions` returns for a split. Amounts are in dollars and must add
  346. up to the transaction amount exactly (on update, the new `amount` if given,
  347. otherwise the current one); categories go on the splits, not on the parent.
  348. Split category names are matched like `categoryName` and echoed back as
  349. `matchedSplitCategories`.
  350. YNAB cannot change the splits of a transaction that is already split, so
  351. `ynab_update_transaction` refuses rather than silently dropping the change.
  352. Delete and recreate the transaction to re-split it.
  353. #### Writes that can half-succeed
  354. YNAB has no endpoint for moving money between categories, so `ynab_move_money`
  355. rewrites both categories' budgeted amounts in two calls. It takes from the
  356. source first, so a failure in between leaves the money in Ready to Assign rather
  357. than double-counted. When that happens the response sets `partial: true` and
  358. carries a `recovery` line with the original amount to restore. `ynab_auto_assign`
  359. behaves the same way: on failure it reports which categories were already funded
  360. and which were left alone.
  361. Tools never throw at the protocol level. Failures come back as an MCP error
  362. result (`isError: true`) with `{ "success": false, "error": "..." }` in the
  363. text content, so a failed write is never mistaken for a successful one.
  364. #### Tool annotations
  365. Every tool advertises MCP annotations (`readOnlyHint`, `destructiveHint`,
  366. `idempotentHint`, `openWorldHint`) alongside its schema. Tools that change
  367. neither YNAB nor the Worker's service state are `readOnlyHint: true`; among the
  368. YNAB writing tools, only `ynab_delete_transaction` and
  369. `ynab_manage_scheduled_transaction` (whose `delete` action cannot be undone) set
  370. `destructiveHint: true`.
  371. A client may use these hints to decide which calls need a confirmation prompt.
  372. #### `cleared` and `flagColor`
  373. `ynab_create_transaction` and `ynab_update_transaction` accept `cleared` as
  374. one of `cleared`, `uncleared`, or `reconciled`. They and
  375. `ynab_manage_scheduled_transaction` accept `flagColor` as one of `red`,
  376. `orange`, `yellow`, `green`, `blue`, `purple`, or `""` to clear an existing
  377. flag.
  378. ## Development
  379. ```bash
  380. npm run watch # rebuild on change
  381. npm test # vitest (watch mode)
  382. npm run test:run # vitest, single run
  383. npm run test:coverage # coverage report
  384. npm run typecheck # typecheck both the node and Worker targets
  385. npm run debug # build, then open the MCP inspector
  386. npm run dev:worker # run the Worker locally with wrangler
  387. npm run deploy # deploy the Worker to Cloudflare
  388. ```
  389. `dist/` is a build artifact and is not tracked in git; `npm run build` regenerates it.
  390. ### Releasing
  391. Bump the version in `package.json` and update `CHANGELOG.md`, then merge to `main` and create a GitHub release tagged in the existing `0.2.0` style (without a `v` prefix). The workflow stages that release with npm; it does not make the package public. The maintainer must run `npm stage list`, review it, and run `npm stage approve` with 2FA to promote it live. Configure a Trusted Publisher on npmjs.com for `ynab-mcp-server`, pointing at GitHub repository `calebl/ynab-mcp-server` and the exact workflow filename `.github/workflows/publish.yml` (the filename must match exactly); under Allowed actions select only `npm stage publish`.
  392. ### Adding a tool
  393. Each tool is a self-contained module in `src/tools/` exporting `name`,
  394. `description`, `inputSchema` (a Zod shape) and `execute(input, api)`. See
  395. `CLAUDE.md` for the full template, then add the module to the `tools` array in
  396. `src/registry.ts` and write a test in `src/tests/`. Registering it there serves
  397. it from both the stdio server and the Worker; mark `writes: true` if the tool
  398. changes data, which is what `YNAB_READ_ONLY` filters on.
  399. Useful references:
  400. - YNAB SDK types: `node_modules/ynab/dist/index.d.ts`
  401. - YNAB OpenAPI spec: <https://api.ynab.com/papi/open_api_spec.yaml>
  402. ## Contributing
  403. Pull requests are welcome. For a new tool or a larger change, please open an
  404. issue first so we can agree on the scope.
  405. 1. Fork the repository and create a branch from `main`.
  406. 2. Make your change and add or update tests in `src/tests/`. New tools follow
  407. the pattern in [Adding a tool](#adding-a-tool).
  408. 3. Run `npm run test:run` and `npm run typecheck`.
  409. 4. Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
  410. for commit messages and the pull request title.
  411. 5. Open a pull request against `main`.
  412. Every pull request runs the test suite on Node.js 22, 24 and 26 and receives an
  413. automated code review. Both checks must pass and review conversations must be
  414. resolved before the pull request can be merged.
  415. ## Compatibility
  416. `budgetId` and `YNAB_BUDGET_ID` are deprecated but still
  417. accepted; there is no removal date. Use `planId` and `YNAB_PLAN_ID` for new
  418. integrations.
  419. ## License
  420. See [LICENSE](./LICENSE).
  421. ## Star History
  422. [![Star History Chart](https://api.star-history.com/chart?repos=calebl/ynab-mcp-server&type=date&legend=top-left)](https://www.star-history.com/?repos=calebl%2Fynab-mcp-server&type=date&legend=top-left)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.