ynab-mcp

★ 9

from dizzlkheinz

MCP server for YNAB. Reconcile bank statements, itemize receipts, manage transactions — all through natural language.

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys

#automation #git #maps

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

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>

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>

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>

For developers

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

Copy & paste — that's it

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

Before it works, you'll need: YNAB_ACCESS_TOKEN

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:

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

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

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

[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

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.

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.

YNAB MCP Server

Demo

What you can do

How it works

Features

How reconciliation works

Tools (28)

For developers

Setup (2 minutes)

1 — Get a YNAB token

2 — Install

3 — Try these prompts

Configuration

Troubleshooting

License