deprekated/ynab-mcp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
YNAB MCP, fable'd into existence~
1 commit 1 branch 0 tags 58 KiB
Find a file
Exact
Kate Temkin f7dfdec665 Initial implementation: MCP server for the YNAB API 
TypeScript MCP server covering the YNAB v1 API (v1.86) with 29 tools:
plans, accounts, categories/groups, budget assignment, payees, months,
money movements, transactions, and scheduled transactions.

Serves stdio by default (for use behind mcp-auth-proxy) or stateless
Streamable HTTP via --http. Reads YNAB_ACCESS_TOKEN from the
environment; YNAB_PLAN_ID optionally pins a default plan.

Includes a nix flake packaging the server via buildNpmPackage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-12 16:29:53 +02:00
src Initial implementation: MCP server for the YNAB API 2026-07-12 16:29:53 +02:00
.gitignore Initial implementation: MCP server for the YNAB API 2026-07-12 16:29:53 +02:00
flake.lock Initial implementation: MCP server for the YNAB API 2026-07-12 16:29:53 +02:00
flake.nix Initial implementation: MCP server for the YNAB API 2026-07-12 16:29:53 +02:00
package-lock.json Initial implementation: MCP server for the YNAB API 2026-07-12 16:29:53 +02:00
package.json Initial implementation: MCP server for the YNAB API 2026-07-12 16:29:53 +02:00
README.md Initial implementation: MCP server for the YNAB API 2026-07-12 16:29:53 +02:00
tsconfig.json Initial implementation: MCP server for the YNAB API 2026-07-12 16:29:53 +02:00

README.md

ynab-mcp

An MCP (Model Context Protocol) server for the YNAB API (v1.86).

Covers the full API surface with 29 tools: plans (budgets), accounts, categories and category groups, budgeted-amount assignment, payees, months, money movements, transactions (list/get/create/update/delete/import), and scheduled transactions.

The server performs no authentication of its own — it is designed to sit behind an MCP proxy that handles auth. It talks to YNAB with a personal access token from the environment.

Configuration

Variable Meaning
YNAB_ACCESS_TOKEN Required. YNAB personal access token (get one here).
YNAB_PLAN_ID Optional default plan (budget) id. Falls back to YNAB's last-used alias.
YNAB_API_URL Optional API base URL override (default https://api.ynab.com/v1).

Running

npm install
npm run build

# stdio (default) — for direct use by an MCP client
YNAB_ACCESS_TOKEN=... node dist/index.js

# Streamable HTTP — for use behind an MCP proxy
YNAB_ACCESS_TOKEN=... node dist/index.js --http --port 8790

The HTTP mode serves MCP at POST /mcp (stateless Streamable HTTP, JSON responses) and a health check at GET /healthz. It binds 127.0.0.1 by default; use --host/$HOST and --port/$PORT to change.

With Nix: nix run .# (stdio) or nix run .# -- --http.

Conventions

  • Milliunits: all monetary amounts are integers in 1/1000 of a currency unit (€12.34 = 12340; outflows negative), matching the YNAB API.
  • plan_id is optional everywhere and defaults to $YNAB_PLAN_ID, then YNAB's last-used plan.
  • Months are ISO dates for the first of the month (2026-07-01) or the literal current.
  • Responses are compacted for LLM consumption: null fields are dropped and deleted entities are filtered out.
  • YNAB rate-limits tokens to 200 requests/hour; errors from the API (including 429s) are returned as tool errors with the API's detail message.