dizzlkheinz/ynab-mcpb

---

Demo

---

What you can do

---

How it works

graph LR
    U(You) -->|Plain English| C[Claude Desktopor any MCP client]
    C -->|MCP protocol| S[YNAB MCP Server35 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

---

Features

• 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 — Choose core, read-only, or full at startup without dynamic registration.
• Delta sync — Fetches only changed data since the last request, keeping things fast.
• Markdown or JSON — All read tools support response_format: human-readable markdown tables (default) or structured JSON.
• MCP-native — Structured outputs, annotations, completions API, and resource templates.

---

How reconciliation works

---

Setup (2 minutes)

1 — Get a YNAB token

1. Open YNAB Web App
2. Go to Account Settings → Developer Settings → New Token
3. Copy it (shown once only)

2 — Install

3 — Try these prompts

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.

---

Tools (35)

---

Configuration

See .env.example for all options.

Write modes and compatibility

preview is the conservative default. A mutation call first runs its existing dry_run path 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-only does not register YNAB mutation tools. enabled preserves the pre-safety direct-write behavior for users who explicitly opt in.

Transaction amounts now prefer amount_decimal (for example, -12.34) or the explicit raw field amount_milliunits (-12340). Category funding similarly prefers budgeted_decimal or budgeted_milliunits. The old amount and budgeted fields remain accepted as deprecated milliunit aliases for backward compatibility; their meaning is never guessed.

Tool profiles

Profiles are selected once at server startup, so clients receive a stable tools/list response:

• core keeps common reads, transaction safety workflows, reconciliation, receipt splitting, scheduled review, and spending analytics.
• read-only exposes every tool explicitly annotated read-only.
• full exposes the complete 35-tool surface, subject to the selected write mode.

Privacy and trust

• 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 at YNAB_EXPORT_PATH (or the platform default). The server does not upload exported files elsewhere.
• Use read-only for no YNAB writes, preview for exact request confirmation, or enabled only when direct writes are an intentional compatibility choice.
• This independent open-source project is not affiliated with or endorsed by YNAB.

---

Troubleshooting

---

For developers

git clone https://github.com/dizzlkheinz/ynab-mcpb.git
cd ynab-mcpb
npm ci --ignore-scripts
npm run build
npm test
npm run test:integration

The build and offline tests require no YNAB credentials. npm test runs unit and performance tests; test:integration runs mocked integration tests. Use test:all, test:coverage, or test:watch for the combined suite, coverage, or watch mode. Pass file/test-name filters directly, for example npm run test:integration -- transactionTools.

To start the server locally, copy .env.example to .env, add your token, and run npm start. Live smoke tests require an explicit RUN_LIVE_YNAB_TESTS=true and run through npm run test:live; SKIP_E2E_TESTS=true disables them.

Builds do not package or install global tools. To create a Claude Desktop bundle, install the official CLI once (npm install --global @anthropic-ai/mcpb), then run npm run build and npm run package:mcpb. Review npm package contents with npm pack --dry-run --ignore-scripts.

Architecture and contributor guidance: CLAUDE.md

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

---

Contributing

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

PRs welcome — run npm test and npm run lint before submitting.

---

License

AGPL-3.0