ynab-mcp

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

GitHub

YNAB MCP Server

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

Download MCPB npm License: AGPL v3 Node.js

Demo

Receipt itemization demo
Paste a receipt → itemized split transaction in seconds

What you can do

WorkflowExample 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

Show workflow diagram 
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."

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

Claude Desktop — MCPB file (recommended)
  1. Download the latest .mcpb from Releases
  2. Drag it into Claude Desktop
  3. Enter your YNAB_ACCESS_TOKEN when prompted
  4. Restart Claude Desktop
Claude Desktop — npx

Add to your Claude Desktop config:

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}
Cline (VS Code) 
{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}
Codex 
[mcp_servers.ynab-mcpb]
command = "npx"
args = ["-y", "@dizzlkheinz/ynab-mcpb@latest"]
env = {"YNAB_ACCESS_TOKEN" = "your-token-here"}
startup_timeout_sec = 120
Any other MCP client
  • Command: npx
  • Args: ["-y", "@dizzlkheinz/ynab-mcpb@latest"]
  • Env: YNAB_ACCESS_TOKEN=<your token>

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

See all tools by category
CategoryTools
Budgetslist_budgets get_budget get_default_budget set_default_budget
Accountslist_accounts get_account create_account
Transactionslist_transactions get_transaction create_transaction create_transactions update_transaction update_transactions delete_transaction export_transactions compare_transactions create_receipt_split_transaction
Categorieslist_categories get_category update_category
Payeeslist_payees get_payee
Monthslist_months get_month
Reconciliationreconcile_account
Utilitiesget_user diagnostic_info clear_cache

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

Full reference: docs/reference/API.md

Configuration

VariableDefaultDescription
YNAB_ACCESS_TOKEN—Required. Your YNAB personal access token.
YNAB_EXPORT_PATH~/DownloadsDirectory for exported transaction files.
YNAB_MCP_ENABLE_DELTAtrueEnable delta sync (only fetch changed data).
YNAB_MCP_CACHE_DEFAULT_TTL_MS300000Cache TTL in milliseconds (5 min).
YNAB_MCP_CACHE_MAX_ENTRIES1000Maximum cache entries before LRU eviction.

See .env.example for all options.

Troubleshooting

SymptomFix
npx failsInstall Node.js 18+, then restart your MCP client.
Auth errorsRegenerate your YNAB token and update YNAB_ACCESS_TOKEN.
Tools not detectedRestart the MCP client after any config change.
Reconciliation issuesOpen an issue with an anonymized CSV sample.

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

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

संबंधित सर्वर