io.github.dizzlkheinz/ynab-mcpb

Official

by dizzlkheinz · TypeScript

MCP server for YNAB (You Need A Budget) — budgets, accounts, transactions, categories

MCP server for YNAB budgeting—manage budgets, accounts, transactions, and categories.

Topics

budgetingmcpbmcpe-serverynab

README.md7 KBView on GitHub

YNAB MCP Server

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

</div>

Demo

<div align="center"> <img src="docs/assets/demo/receipt-itemization-demo-lite.gif" alt="Receipt itemization demo" width="820" /> <br/> <sub>Paste a receipt → itemized split transaction in seconds</sub> </div>

What you can do

Workflow	Example prompt
Receipt split	"Create a split transaction for this receipt and allocate tax."
Bank reconciliation	"Reconcile my checking account using this CSV."
Spending analysis	"What did I spend on takeout this month?"
Transaction creation	"Create a transaction: $42.18 at Trader Joe's yesterday."
Month overview	"Show my budget summary for January."

How it works

mermaid

graph LR
    U(You) -->|Plain English| C[Claude Desktop<br/>or any MCP client]
    C -->|MCP protocol| S[YNAB MCP Server<br/>28 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.
28 YNAB tools — Full coverage of budgets, accounts, transactions, categories, payees, months, and utilities.
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

<details> <summary>Show workflow diagram</summary>

mermaid

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

</details>

Setup (2 minutes)

1 — Get a YNAB token

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

2 — Install

<details> <summary><strong>Claude Desktop — MCPB file (recommended)</strong></summary>

Download the latest .mcpb from Releases
Drag it into Claude Desktop
Enter your YNAB_ACCESS_TOKEN when prompted
Restart Claude Desktop

</details> <details> <summary><strong>Claude Desktop — npx</strong></summary>

Add to your Claude Desktop config:

json

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

</details> <details> <summary><strong>Cline (VS Code)</strong></summary>

json

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

</details> <details> <summary><strong>Codex</strong></summary>

toml

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

</details> <details> <summary><strong>Any other MCP client</strong></summary>

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

</details>

3 — Try these prompts

code

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 (28)

<details> <summary>See all tools by category</summary>

Category	Tools
Budgets	`list_budgets` `get_budget` `get_default_budget` `set_default_budget`
Accounts	`list_accounts` `get_account` `create_account`
Transactions	`list_transactions` `get_transaction` `create_transaction` `create_transactions` `update_transaction` `update_transactions` `delete_transaction` `export_transactions` `compare_transactions` `create_receipt_split_transaction`
Categories	`list_categories` `get_category` `update_category`
Payees	`list_payees` `get_payee`
Months	`list_months` `get_month`
Reconciliation	`reconcile_account`
Utilities	`get_user` `diagnostic_info` `clear_cache`

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

Full reference: docs/reference/API.md

</details>

Configuration

Variable	Default	Description
`YNAB_ACCESS_TOKEN`	—	Required. Your YNAB personal access token.
`YNAB_EXPORT_PATH`	`~/Downloads`	Directory for exported transaction files.
`YNAB_MCP_ENABLE_DELTA`	`true`	Enable delta sync (only fetch changed data).
`YNAB_MCP_CACHE_DEFAULT_TTL_MS`	`300000`	Cache TTL in milliseconds (5 min).
`YNAB_MCP_CACHE_MAX_ENTRIES`	`1000`	Maximum cache entries before LRU eviction.

See .env.example for all options.

Troubleshooting

Symptom	Fix
`npx` fails	Install Node.js 18+, then restart your MCP client.
Auth errors	Regenerate your YNAB token and update `YNAB_ACCESS_TOKEN`.
Tools not detected	Restart the MCP client after any config change.
Reconciliation issues	Open an issue with an anonymized CSV sample.

For developers

bash

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

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

Install

Configuration

Environment variables

YNAB_ACCESS_TOKENrequiredsecret

YNAB Personal Access Token from https://app.youneedabudget.com/settings/developer

claude_desktop_config.json

{
  "mcpServers": {
    "ynab-mcpb": {
      "command": "npx",
      "args": [
        "-y",
        "@dizzlkheinz/ynab-mcpb@0.26.10"
      ],
      "env": {
        "YNAB_ACCESS_TOKEN": "<YOUR_YNAB_ACCESS_TOKEN>"
      }
    }
  }
}