ynab-mcp

Connect YNAB to any AI assistant. Manage your budget in plain English.

graph LR U(You) -->|Plain English| C[Claude Desktop<br/>or any MCP client] C -->|MCP protocol| S[YNAB MCP Server<br/>35 tools] S -->|YNAB API| Y[(Your Budget)] style S fill:#2563EB,color:#fff,stroke:#1d4ed8 style Y fill:#16a34a,color:#fff,stroke:#15803d style C fill:#7c3aed,color:#fff,stroke:#6d28d9

- Receipt itemization— Paste a receipt, get an itemized split transaction with tax allocation automatically distributed across line items.
- Bank reconciliation (beta)— Import a bank CSV, fuzzy-match against YNAB, detect missing or mismatched transactions, and apply bulk fixes.
- 35 YNAB tools— Full coverage plus scheduled transactions and deterministic period analytics.
- Write safety by default— Preview mode requires a short-lived, single-use confirmation bound to the exact validated request.
- Smaller tool profiles— Choosecore,read-only, orfullat startup without dynamic registration.
- Delta sync— Fetches only changed data since the last request, keeping things fast.
- Markdown or JSON— All read tools supportresponse_format: human-readable markdown tables (default) or structured JSON.
- MCP-native— Structured outputs, annotations, completions API, and resource templates.

sequenceDiagram participant You participant Claude participant MCP as YNAB MCP Server participant YNAB You->>Claude: "Reconcile my checking<br/>with this CSV" Claude->>MCP: reconcile_account(csv_data) MCP->>YNAB: Fetch transactions YNAB-->>MCP: YNAB transactions MCP->>MCP: Parse CSV<br/>Fuzzy-match payees & dates<br/>Detect missing / mismatched MCP-->>Claude: Matches + recommendations Claude->>You: "Found 47 matches, 3 missing.<br/>Apply changes?" You->>Claude: "Yes" Claude->>MCP: Apply recommended changes MCP->>YNAB: Create / update transactions MCP-->>Claude: Done Claude->>You: "3 transactions created,<br/>account reconciled."

- OpenYNAB Web App
- Go toAccount Settings → Developer Settings → New Token
- Copy it (shown once only)
- Download the latest.mcpbfromReleases
- Drag it into Claude Desktop
- Enter yourYNAB_ACCESS_TOKENwhen prompted
- Restart Claude Desktop

{ "mcpServers": { "ynab": { "command": "npx", "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"], "env": { "YNAB_ACCESS_TOKEN": "your-token-here" } } } }

{ "mcpServers": { "ynab": { "command": "npx", "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"], "env": { "YNAB_ACCESS_TOKEN": "your-token-here" } } } }

[mcp_servers.ynab-mcpb] command = "npx" args = ["-y", "@dizzlkheinz/ynab-mcpb@latest"] env = {"YNAB_ACCESS_TOKEN" = "your-token-here"} startup_timeout_sec = 120

- Command:npx
- Args:["-y", "@dizzlkheinz/ynab-mcpb@latest"]
- Env:YNAB_ACCESS_TOKEN=<your token>

List my budgets and set the default to my main budget. Show recent transactions in my checking account. How much did I spend on groceries in the last 30 days? Create a transaction: $42.18 at Trader Joe's yesterday.

All read tools acceptresponse_format("markdown"or"json", default:"markdown").

previewis the conservative default. A mutation call first runs its existingdry_runpath and returns a confirmation token. That token expires after two minutes, can be used once, and only authorizes the same canonical tool name and validated arguments.read-onlydoes not register YNAB mutation tools.enabledpreserves the pre-safety direct-write behavior for users who explicitly opt in.

Transaction amounts now preferamount_decimal(for example,-12.34) or the explicit raw fieldamount_milliunits(-12340). Category funding similarly prefersbudgeted_decimalorbudgeted_milliunits. The oldamountandbudgetedfields remain accepted as deprecated milliunit aliases for backward compatibility; their meaning is never guessed.

Profiles are selected once at server startup, so clients receive a stabletools/listresponse:

- corekeeps common reads, transaction safety workflows, reconciliation, receipt splitting, scheduled review, and spending analytics.
- read-onlyexposes every tool explicitly annotated read-only.
- fullexposes the complete 35-tool surface, subject to the selected write mode.

- The server process runs locally and communicates with YNAB over YNAB's API.
- Your YNAB personal access token is sensitive. Store it in your MCP client's secret configuration and never paste it into a conversation, issue, fixture, or log.
- Financial data returned by tools and included in a conversation may be processed by the AI provider selected in your MCP client. Review that provider's data controls before sharing sensitive details.
- Transaction exports remain on local disk atYNAB_EXPORT_PATH(or the platform default). The server does not upload exported files elsewhere.
- Useread-onlyfor no YNAB writes,previewfor exact request confirmation, orenabledonly when direct writes are an intentional compatibility choice.
- This independent open-source project is not affiliated with or endorsed by YNAB.

git clone https://github.com/dizzlkheinz/ynab-mcpb.git cd ynab-mcpb npm install cp .env.example .env # add YNAB_ACCESS_TOKEN npm run build npm test

Architecture and contributor guidance:CLAUDE.md

Reconciliation architecture:docs/technical/reconciliation-system-architecture.md

Bug reports and CSV edge-case repros are very welcome, especially for bank reconciliation:Open an issue

Execute stock and crypto trades via Trade Agent