{
  "markdown": "<div align=\"center\">\n\n# YNAB MCP Server\n\n**Connect YNAB to any AI assistant. Manage your budget in plain English.**\n\n[![Download MCPB](https://img.shields.io/badge/Download-MCPB-2563EB?style=for-the-badge&logo=github&logoColor=white)](https://github.com/dizzlkheinz/ynab-mcpb/releases/latest)\n[![npm](https://img.shields.io/npm/v/@dizzlkheinz/ynab-mcpb.svg?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/@dizzlkheinz/ynab-mcpb)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue?style=for-the-badge)](LICENSE)\n[![Node.js](https://img.shields.io/badge/Node.js-24%2B-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org)\n\n</div>\n\n---\n\n## Demo\n\n<div align=\"center\">\n  <img src=\"docs/assets/demo/receipt-itemization-demo-lite.gif\" alt=\"Receipt itemization demo\" width=\"820\" />\n  <br/>\n  <sub>Paste a receipt &rarr; itemized split transaction in seconds</sub>\n</div>\n\n---\n\n## What you can do\n\n| Workflow | Example prompt |\n|---|---|\n| Receipt split | \"Create a split transaction for this receipt and allocate tax.\" |\n| Bank reconciliation | \"Reconcile my checking account using this CSV.\" |\n| Spending analysis | \"What did I spend on takeout this month?\" |\n| Scheduled cash flow | \"What scheduled bills and income are due this month?\" |\n| Transaction creation | \"Create a transaction: $42.18 at Trader Joe's yesterday.\" |\n| Month overview | \"Show my budget summary for January.\" |\n\n---\n\n## How it works\n\n```mermaid\ngraph LR\n    U(You) -->|Plain English| C[Claude Desktop<br/>or any MCP client]\n    C -->|MCP protocol| S[YNAB MCP Server<br/>35 tools]\n    S -->|YNAB API| Y[(Your Budget)]\n\n    style S fill:#2563EB,color:#fff,stroke:#1d4ed8\n    style Y fill:#16a34a,color:#fff,stroke:#15803d\n    style C fill:#7c3aed,color:#fff,stroke:#6d28d9\n```\n\n---\n\n## Features\n\n- **Receipt itemization** — Paste a receipt, get an itemized split transaction with tax allocation automatically distributed across line items.\n- **Bank reconciliation (beta)** — Import a bank CSV, fuzzy-match against YNAB, detect missing or mismatched transactions, and apply bulk fixes.\n- **35 YNAB tools** — Full coverage plus scheduled transactions and deterministic period analytics.\n- **Write safety by default** — Preview mode requires a short-lived, single-use confirmation bound to the exact validated request.\n- **Smaller tool profiles** — Choose `core`, `read-only`, or `full` at startup without dynamic registration.\n- **Delta sync** — Fetches only changed data since the last request, keeping things fast.\n- **Markdown or JSON** — All read tools support `response_format`: human-readable markdown tables (default) or structured JSON.\n- **MCP-native** — Structured outputs, annotations, completions API, and resource templates.\n\n---\n\n## How reconciliation works\n\n<details>\n<summary>Show workflow diagram</summary>\n\n```mermaid\nsequenceDiagram\n    participant You\n    participant Claude\n    participant MCP as YNAB MCP Server\n    participant YNAB\n\n    You->>Claude: \"Reconcile my checking<br/>with this CSV\"\n    Claude->>MCP: reconcile_account(csv_data)\n    MCP->>YNAB: Fetch transactions\n    YNAB-->>MCP: YNAB transactions\n    MCP->>MCP: Parse CSV<br/>Fuzzy-match payees & dates<br/>Detect missing / mismatched\n    MCP-->>Claude: Matches + recommendations\n    Claude->>You: \"Found 47 matches, 3 missing.<br/>Apply changes?\"\n    You->>Claude: \"Yes\"\n    Claude->>MCP: Apply recommended changes\n    MCP->>YNAB: Create / update transactions\n    MCP-->>Claude: Done\n    Claude->>You: \"3 transactions created,<br/>account reconciled.\"\n```\n\n</details>\n\n---\n\n## Setup (2 minutes)\n\n### 1 — Get a YNAB token\n\n1. Open [YNAB Web App](https://app.youneedabudget.com)\n2. Go to **Account Settings &rarr; Developer Settings &rarr; New Token**\n3. Copy it (shown once only)\n\n### 2 — Install\n\n<details>\n<summary><strong>Claude Desktop — MCPB file (recommended)</strong></summary>\n\n1. Download the latest `.mcpb` from [Releases](https://github.com/dizzlkheinz/ynab-mcpb/releases/latest)\n2. Drag it into Claude Desktop\n3. Enter your `YNAB_ACCESS_TOKEN` when prompted\n4. Restart Claude Desktop\n\n</details>\n\n<details>\n<summary><strong>Claude Desktop — npx</strong></summary>\n\nAdd to your Claude Desktop config:\n\n```json\n{\n  \"mcpServers\": {\n    \"ynab\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@dizzlkheinz/ynab-mcpb@latest\"],\n      \"env\": {\n        \"YNAB_ACCESS_TOKEN\": \"your-token-here\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Cline (VS Code)</strong></summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"ynab\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@dizzlkheinz/ynab-mcpb@latest\"],\n      \"env\": {\n        \"YNAB_ACCESS_TOKEN\": \"your-token-here\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Codex</strong></summary>\n\n```toml\n[mcp_servers.ynab-mcpb]\ncommand = \"npx\"\nargs = [\"-y\", \"@dizzlkheinz/ynab-mcpb@latest\"]\nenv = {\"YNAB_ACCESS_TOKEN\" = \"your-token-here\"}\nstartup_timeout_sec = 120\n```\n\n</details>\n\n<details>\n<summary><strong>Any other MCP client</strong></summary>\n\n- **Command:** `npx`\n- **Args:** `[\"-y\", \"@dizzlkheinz/ynab-mcpb@latest\"]`\n- **Env:** `YNAB_ACCESS_TOKEN=<your token>`\n\n</details>\n\n### 3 — Try these prompts\n\n```\nList my budgets and set the default to my main budget.\nShow recent transactions in my checking account.\nHow much did I spend on groceries in the last 30 days?\nCreate a transaction: $42.18 at Trader Joe's yesterday.\n```\n\n---\n\n## Tools (35)\n\n<details>\n<summary>See all tools by category</summary>\n\n| Category | Tools |\n|---|---|\n| Budgets | `list_budgets` `get_budget` `get_default_budget` `set_default_budget` |\n| Accounts | `list_accounts` `get_account` `create_account` |\n| Transactions | `list_transactions` `get_transaction` `create_transaction` `create_transactions` `update_transaction` `update_transactions` `delete_transaction` `export_transactions` `compare_transactions` `create_receipt_split_transaction` |\n| Categories | `list_categories` `get_category` `update_category` |\n| Payees | `list_payees` `get_payee` |\n| Months | `list_months` `get_month` |\n| Reconciliation | `reconcile_account` |\n| Scheduled transactions | `list_scheduled_transactions` `get_scheduled_transaction` `create_scheduled_transaction` `update_scheduled_transaction` `delete_scheduled_transaction` |\n| Analytics | `analyze_spending` `compare_spending_periods` |\n| Utilities | `get_user` `diagnostic_info` `clear_cache` |\n\nAll read tools accept `response_format` (`\"markdown\"` or `\"json\"`, default: `\"markdown\"`).\n\nFull reference: [docs/reference/API.md](docs/reference/API.md)\n\n</details>\n\n---\n\n## Configuration\n\n| Variable | Default | Description |\n|---|---|---|\n| `YNAB_ACCESS_TOKEN` | — | **Required.** Your YNAB personal access token. |\n| `YNAB_EXPORT_PATH` | `~/Downloads` | Directory for exported transaction files. |\n| `YNAB_MCP_ENABLE_DELTA` | `true` | Enable delta sync (only fetch changed data). |\n| `YNAB_MCP_WRITE_MODE` | `preview` | `read-only` hides YNAB mutations; `preview` requires exact confirmation; `enabled` permits direct writes. |\n| `YNAB_MCP_TOOL_PROFILE` | `full` | `core`, `read-only`, or `full` startup tool surface. |\n| `YNAB_MCP_CACHE_DEFAULT_TTL_MS` | `300000` | Cache TTL in milliseconds (5 min). |\n| `YNAB_MCP_CACHE_MAX_ENTRIES` | `1000` | Maximum cache entries before LRU eviction. |\n\nSee `.env.example` for all options.\n\n### Write modes and compatibility\n\n`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.\n\nTransaction 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.\n\n### Tool profiles\n\nProfiles are selected once at server startup, so clients receive a stable `tools/list` response:\n\n- `core` keeps common reads, transaction safety workflows, reconciliation, receipt splitting, scheduled review, and spending analytics.\n- `read-only` exposes every tool explicitly annotated read-only.\n- `full` exposes the complete 35-tool surface, subject to the selected write mode.\n\n## Privacy and trust\n\n- The server process runs locally and communicates with YNAB over YNAB's API.\n- 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.\n- 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.\n- Transaction exports remain on local disk at `YNAB_EXPORT_PATH` (or the platform default). The server does not upload exported files elsewhere.\n- Use `read-only` for no YNAB writes, `preview` for exact request confirmation, or `enabled` only when direct writes are an intentional compatibility choice.\n- This independent open-source project is not affiliated with or endorsed by YNAB.\n\n---\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---|---|\n| `npx` fails | Install Node.js 24+, then restart your MCP client. |\n| Auth errors | Regenerate your YNAB token and update `YNAB_ACCESS_TOKEN`. |\n| Tools not detected | Restart the MCP client after any config change. |\n| Reconciliation issues | [Open an issue](https://github.com/dizzlkheinz/ynab-mcpb/issues) with an anonymized CSV sample. |\n\n---\n\n## For developers\n\n```bash\ngit clone https://github.com/dizzlkheinz/ynab-mcpb.git\ncd ynab-mcpb\nnpm install\ncp .env.example .env   # add YNAB_ACCESS_TOKEN\nnpm run build\nnpm test\n```\n\nArchitecture and contributor guidance: [`CLAUDE.md`](CLAUDE.md)\n\nReconciliation architecture: [`docs/technical/reconciliation-system-architecture.md`](docs/technical/reconciliation-system-architecture.md)\n\n---\n\n## Contributing\n\nBug reports and CSV edge-case repros are very welcome, especially for bank reconciliation:\n[Open an issue](https://github.com/dizzlkheinz/ynab-mcpb/issues)\n\nPRs welcome — run `npm test` and `npm run lint` before submitting.\n\n---\n\n## License\n\n[AGPL-3.0](LICENSE)\n",
  "bytes": 10466,
  "sha": "bef677c2dcfcdf25e409c5ba9dabb51b5a5f78f6e5a4eae44b7f271b848b12cb",
  "repo_slug": "dizzlkheinz/ynab-mcpb",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dizzlkheinz_ynab_mcpb_37949168/readme"
}