io.github.dizzlkheinz/ynab-mcpb
MCP server for YNAB (You Need A Budget) β budgets, accounts, transactions, categories
Ask AI about io.github.dizzlkheinz/ynab-mcpb
Powered by Claude Β· Grounded in docs
I know everything about io.github.dizzlkheinz/ynab-mcpb. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Demo
Paste a receipt β itemized split transaction in seconds
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
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
- Open YNAB Web App
- Go to Account Settings β Developer Settings β New Token
- Copy it (shown once only)
2 β Install
Claude Desktop β MCPB file (recommended)
- Download the latest
.mcpbfrom Releases - Drag it into Claude Desktop
- Enter your
YNAB_ACCESS_TOKENwhen prompted - 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
| 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
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
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.
