YNAB MCP Server

Connect your YNAB budget to Claude Desktop and other AI assistants using the Model Context Protocol (MCP). Ask questions about your spending, create transactions, reconcile accounts, and manage your budget using natural language.

What Can You Do?

• Ask Questions: "How much did I spend on groceries last month?" or "What's my credit card balance?"
• Manage Transactions: Create, update, or delete transactions without opening YNAB
• Split Receipts: Create itemized transactions from receipts with automatic tax allocation across items
• Reconcile Accounts: Import and compare bank statements to find missing transactions
• Analyze Spending: Get insights into spending patterns and budget performance
• Set Budgets: Adjust category budgets and move money between categories

All monetary amounts are automatically converted to dollars (YNAB stores them in milliunits internally), so everything is human-readable.

Quick Start

Step 1: Get Your YNAB Access Token

1. Log in to YNAB Web App
2. Go to Account Settings → Developer Settings
3. Click New Token
4. Give it a name (e.g., "MCP Server")
5. Copy the token (you'll only see it once!)

Step 2: Install in Your MCP Client

Option A: Download the Extension

1. Download the latest .mcpb file from Releases
2. Drag and drop it into Claude Desktop
3. Paste your YNAB Access Token when prompted
4. Restart Claude Desktop

Option B: Use npx

Add this to your Claude Desktop MCP settings file:

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

Add this to your Cline MCP settings:

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

For any MCP-compatible client, configure the server with:

Command: npx Arguments: ["-y", "@dizzlkheinz/ynab-mcp-server"] Environment Variables:

• YNAB_ACCESS_TOKEN: Your YNAB Personal Access Token

Refer to your MCP client's documentation for specific configuration steps.

Step 3: Start Using It

Ask your AI assistant questions like:

• "What's my checking account balance?"
• "How much have I spent on dining out this month?"
• "List my recent transactions"
• "Set my groceries budget to $500"

That's it! You're ready to manage your budget with AI.

Optional Configuration

Most users won't need to change these settings, but they're available if you need them:

Export Location:

• YNAB_EXPORT_PATH — Where to save exported transaction files (defaults to Downloads folder)

Example:

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@dizzlkheinz/ynab-mcp-server"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here",
        "YNAB_EXPORT_PATH": "C:\\Users\\YourName\\Documents"
      }
    }
  }
}

For advanced configuration options (caching, output formatting), see the Configuration Guide.

What's Available

The server gives Claude access to 30 tools organized by function. You don't need to know the tool names - just ask Claude in natural language and it will use the right tools.

Budget & Account Info

• View budgets, accounts, categories, payees
• Check balances and category budgets
• See monthly spending summaries

Transactions

• List, create, update, or delete transactions
• Import and reconcile bank statements
• Export transactions to files
• Create split transactions from receipts

Analysis

• Compare spending across time periods
• Find missing transactions
• Track budget performance

For the complete list with technical details, see the API Reference.

Need Help?

• Troubleshooting Guide - Common issues and solutions
• Full Documentation - Complete guides and API reference
• GitHub Issues - Report bugs or request features

For Developers

Want to contribute or build from source?

• Development Guide - Setup and best practices
• Architecture Overview - How the code is organized
• Testing Guide - Running and writing tests

Quick start for development:

git clone <repository-url>
cd ynab-mcp-server
npm install
npm run build
npm test

Security & Privacy

Your YNAB access token is stored securely and never logged. All communication with YNAB's API uses HTTPS, and the server validates all inputs to prevent errors and security issues.

Contributing

Contributions welcome! Please:

1. Open an issue to discuss your idea
2. Fork the repository and make your changes
3. Add tests for new features
4. Submit a pull request

See the Development Guide for details.

License

Licensed under AGPL-3.0. Free to use and modify, but derivative works must also be open source.

Built with:

• YNAB API - Official YNAB REST API
• Model Context Protocol - AI integration standard
• Claude Desktop - AI assistant with MCP support