YNAB MCP Server

YNAB MCP Server

Connect YNAB to Claude Desktop (or any MCP client) and manage your budget in plain English.

Ask things like:

• "What did I spend on takeout this month?"
• "Create a split transaction for this receipt and allocate tax."
• "Reconcile my checking account from this CSV."

60-second demo

Receipt workflow demo (3x speed, lightweight embed):

Open demo GIF directly

• Receipt flow: paste receipt -> create transaction
• Reconciliation flow: import CSV -> review matches -> apply changes

Why install this

• Powerful receipt itemization and split creation
• Bank CSV reconciliation with fuzzy matching (beta)
• Works with any MCP-compatible client
• Local MCP server process on your machine, using your YNAB token

Features

• Receipt itemization: Paste a receipt and create itemized split transactions with tax allocation.
• Bank reconciliation (beta): Import CSV, fuzzy-match against YNAB, detect missing/mismatched items, and apply fixes.
• Full YNAB operations: Budgets, accounts, transactions, categories, payees, and month analysis.
• MCP-native implementation: Structured tool outputs, annotations, completions, and resource templates.

2-minute setup

1) Get a YNAB access token

1. Open YNAB Web App
2. Go to Account Settings -> Developer Settings
3. Click New Token
4. Copy it (shown once)

2) Add this MCP server

Use one of the options below:

Claude Desktop (recommended)

Option A (.mcpb package):

1. Download latest .mcpb from Releases
2. Drag into Claude Desktop
3. Paste YNAB_ACCESS_TOKEN
4. Restart Claude Desktop

Option B (npx):

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

Optional configuration

• YNAB_EXPORT_PATH - Directory for exported transaction files
• YNAB_MCP_ENABLE_DELTA - Enable/disable delta sync optimization (true by default)
• Caching options are available in .env.example

Tools and docs

• 28 tools across budgets, accounts, transactions, categories, payees, months, reconciliation, and utilities
• Full tool reference: docs/reference/API.md
• Reconciliation architecture: docs/technical/reconciliation-system-architecture.md

Troubleshooting

• If npx fails, make sure Node.js and npm are installed, then restart your MCP client.
• If tools return auth errors, regenerate your YNAB token and update YNAB_ACCESS_TOKEN.
• If a client does not detect tools, restart the client after MCP config changes.
• For parser/matching issues in reconciliation, open an issue with anonymized CSV samples.

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

Contributing

Bug reports and small repros are very welcome, especially for bank CSV reconciliation edge cases:Open an issue

PRs welcome. Please run npm test and npm run lint before submitting.

License

AGPL-3.0