dizzlkheinz/ynab-mcpb

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

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

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

[mcp_servers.ynab-mcpb]
command = "npx"
args = ["-y", "@dizzlkheinz/ynab-mcpb@latest"]
env = {"YNAB_ACCESS_TOKEN" = "your-token-here"}
startup_timeout_sec = 120

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-mcpb@latest"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here",
        "YNAB_EXPORT_PATH": "C:\\Users\\YourName\\Documents"
      }
    }
  }
}

For advanced configuration options (caching, output formatting), see the .env.example file in the repository.

What's Available

The server gives Claude access to 29 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

MCP Resources

• Access budget and account data via URI patterns (e.g., ynab://budgets/{id})
• Static resources: ynab://budgets, ynab://user

For the complete list with technical details, see the .

Need Help?

• - Complete tool documentation
• GitHub Issues - Report bugs or request features

For Developers

Want to contribute or build from source?

Development Setup

1. Clone the repository:

   git clone https://github.com/dizzlkheinz/ynab-mcpb.git
   cd ynab-mcpb
   

2. Install dependencies:

   npm install
   

3. Create your environment file: Copy the example environment file to a new .env file:

   cp .env.example .env
   

   Open the .env file and add your YNAB Personal Access Token:

   YNAB_ACCESS_TOKEN="your-token-here"
   

4. Build and test the project:

   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 CLAUDE.md for development details and architecture overview.

License

Licensed under . 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