YNAB MCP Server

A comprehensive Model Context Protocol (MCP) server for YNAB (You Need A Budget) that enables AI assistants like Claude Desktop to read your budget, analyze spending patterns, detect subscriptions, and provide personalized financial insights—all through natural conversation.

Why YNAB MCP?

Traditional YNAB integrations require manual API calls or custom scripting. This MCP server lets you:

• Talk to your budget naturally — Ask Claude "Am I overspending on dining out?" and get instant insights
• Get AI-powered financial analysis — Subscription detection, spending trends, savings recommendations, and budget health scores
• Stay safe by default — Read-only mode protects against accidental changes
• Access everything — 66 tools total: comprehensive YNAB API coverage (40 tools), 23 custom analytics tools, and 3 system tools

Features

| Feature | Description | |---------|-------------| | Broad API Coverage | 66 MCP tools spanning the YNAB API endpoints | | Advanced Analytics | 23 tools for spending analysis, trend detection, and financial insights | | Read-Only by Default | Write operations require explicit opt-in (YNAB_READ_ONLY=false) | | Smart Rate Limiting | Token bucket algorithm with 180 req/hour budget (10% safety margin) | | Intelligent Caching | Reduces API calls for infrequently changing data | | Type-Safe | Full TypeScript implementation with Zod schema validation |

Quick Start

Prerequisites

• A YNAB account with API access
• A YNAB Personal Access Token (get one here)

Installation Options

Option 1: npx (Easiest)

No installation required—run directly:

npx ynab-mcp

Option 2: Docker

docker run -e YNAB_ACCESS_TOKEN=your_token ghcr.io/auzroz/ynab-mcp:latest

Option 3: Install from Source

# Clone the repository
git clone https://github.com/auzroz/ynab-mcp.git
cd ynab-mcp

# Install dependencies and build
npm install
npm run build

# Run the server
npm start

Configuration

The server is configured via environment variables:

| Variable | Required | Description | |----------|----------|-------------| | YNAB_ACCESS_TOKEN | Yes | Your YNAB Personal Access Token | | YNAB_BUDGET_ID | No | Default budget UUID (uses "last-used" if not set) | | YNAB_READ_ONLY | No | Set to false to enable write operations (default: true) |

Remote / HTTP mode

By default the server speaks stdio (local). Set MCP_TRANSPORT=http to run it as a remote server over the MCP Streamable HTTP transport at POST /mcp, with a plain GET /health for load balancers. Each session gets an isolated client/cache/rate-limiter/audit-log.

| Variable | Description | |----------|-------------| | MCP_TRANSPORT | stdio (default) or http | | PORT | HTTP port (default 3000) | | ALLOWED_HOSTS / ALLOWED_ORIGINS | Comma-separated allowlists for DNS-rebinding protection | | ENABLE_DNS_REBINDING_PROTECTION | Enable Origin/Host checks (needs an allowlist) |

Multi-user (YNAB OAuth). Configure a YNAB OAuth app + ENCRYPTION_KEY + PUBLIC_URL and the server becomes an OAuth 2.1 Authorization Server federated to YNAB: many users connect their own YNAB accounts to one instance, each isolated, choosing read-only or read-write at consent. See docs/REMOTE_HOSTING.md for the full deployer guide (registering the YNAB app, storage, TLS).

Single-user (header auth). If the OAuth variables aren't all set, HTTP mode takes the YNAB token per request via the X-YNAB-Token header (falling back to YNAB_ACCESS_TOKEN for one user). Serve behind TLS.

MCP_TRANSPORT=http PORT=3000 YNAB_ACCESS_TOKEN=… npm start
# connect an MCP client via the mcp-remote shim:
npx mcp-remote http://localhost:3000/mcp --header "X-YNAB-Token: <your-token>"

Claude Desktop Integration

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (Recommended)

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["ynab-mcp"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Using Docker

{
  "mcpServers": {
    "ynab": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "YNAB_ACCESS_TOKEN",
        "ghcr.io/auzroz/ynab-mcp:latest"
      ],
      "env": {
        "YNAB_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Using Local Build

{
  "mcpServers": {
    "ynab": {
      "command": "node",
      "args": ["/path/to/ynab-mcp/dist/index.js"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Example Conversations

Once connected, try asking Claude:

| Question | Tool Used | |----------|-----------| | "What's my current net worth?" | ynab_net_worth | | "How much did I spend on dining out this month?" | ynab_list_category_transactions | | "What subscriptions do I have?" | ynab_detect_recurring | | "Is my budget in good shape?" | ynab_budget_health | | "Where can I cut back on spending?" | ynab_savings_opportunities | | "Am I on track this month?" | ynab_spending_pace | | "Compare this month to last month" | ynab_monthly_comparison |

Available Tools (66 Total)

Analytics Tools (23)

These tools provide AI-powered financial insights beyond basic YNAB functionality:

| Tool | Description | |------|-------------| | ynab_detect_recurring | Find subscription patterns and recurring payments | | ynab_spending_analysis | Analyze spending trends by category | | ynab_budget_health | Assess overall budget health with score and alerts | | ynab_savings_opportunities | Identify potential areas to save money | | ynab_budget_vs_actuals | Compare budgeted vs actual spending | | ynab_quick_summary | At-a-glance budget status overview | | ynab_income_expense | Income vs expense breakdown and trends | | ynab_net_worth | Calculate total net worth from all accounts | | ynab_goal_progress | Track goal funding progress with projections | | ynab_spending_by_payee | Analyze spending by merchant/payee | | ynab_unused_categories | Find inactive or unused categories | | ynab_monthly_comparison | Month-over-month spending comparison | | ynab_spending_trends | Multi-month trend analysis with projections | | ynab_cash_flow_forecast | Project future cash flow based on scheduled transactions | | ynab_reconciliation_helper | Help with account reconciliation | | ynab_budget_suggestions | Get budget suggestions based on history | | ynab_overspending_alerts | Quick check for overspent categories | | ynab_transaction_search | Powerful multi-filter transaction search | | ynab_spending_pace | Track daily spending rate vs target | | ynab_category_balances | Quick category balance lookup | | ynab_credit_card_status | Credit card balances vs payment categories | | ynab_age_of_money | Age of money metric with explanation | | ynab_preview_scheduled_transaction | Preview the budget impact of a scheduled transaction |

Core YNAB API Tools (40)

Coverage of the YNAB API endpoints:

• ynab_get_user — Get authenticated user information

• ynab_list_budgets — List all accessible budgets
• ynab_get_budget — Get detailed budget information
• ynab_get_budget_settings — Get budget settings (currency format, etc.)

• ynab_list_accounts — List all accounts with balances
• ynab_get_account — Get specific account details
• ynab_create_account — Create a new account (write mode)

• ynab_list_categories — List all category groups and categories
• ynab_get_category — Get category details
• ynab_get_month_category — Get category budget for specific month
• ynab_update_category — Update category budgeted amount (write mode)
• ynab_create_category — Create a new category in a group (write mode)
• ynab_create_category_group — Create a new category group (write mode)
• ynab_update_category_group — Rename a category group (write mode)

• ynab_list_payees — List all payees (merchants/vendors)
• ynab_get_payee — Get specific payee details
• ynab_create_payee — Create a new payee (write mode)
• ynab_update_payee — Rename a payee (write mode)
• ynab_list_payee_locations — List all payee locations for mapping
• ynab_get_payee_location — Get specific payee location
• ynab_list_payee_locations_by_payee — List locations for a specific payee

• ynab_list_months — List all budget months
• ynab_get_month — Get detailed month summary with categories

• ynab_list_transactions — List transactions with filters
• ynab_get_transaction — Get transaction details
• ynab_create_transaction — Create a new transaction (write mode)
• ynab_create_transactions — Bulk create transactions (write mode)
• ynab_update_transaction — Update a transaction (write mode)
• ynab_update_transactions — Bulk update transactions (write mode)
• ynab_delete_transaction — Delete a transaction (write mode)
• ynab_list_account_transactions — List transactions for a specific account
• ynab_list_category_transactions — List transactions for a specific category
• ynab_list_payee_transactions — List transactions for a specific payee
• ynab_import_transactions — Trigger import from linked banks (write mode)

• ynab_list_scheduled_transactions — List scheduled/recurring transactions
• ynab_get_scheduled_transaction — Get scheduled transaction details
• ynab_create_scheduled_transaction — Create a scheduled transaction (write mode)
• ynab_update_scheduled_transaction — Update a scheduled transaction (write mode)
• ynab_delete_scheduled_transaction — Delete a scheduled transaction (write mode)

• ynab_list_money_movements — List moves of funds between categories

• ynab_rate_limit_status — Check API rate limit status
• ynab_audit_log — View write operation audit log
• ynab_health_check — Test API connectivity

Available Prompts

Beyond raw tool access, the server exposes 7 MCP Prompts — guided workflows grounded in YNAB's own budgeting methodology (the Four Rules, Age of Money, True Expenses) that orchestrate several tools into a single review. Any MCP client that supports the prompts capability can invoke them directly.

| Prompt | What it does | |--------|---------------| | ynab-pulse-check | Fast daily-style status check | | ynab-monthly-review | Full end-of-month budget review and next month's suggested targets | | ynab-assign-money | Give Every Dollar a Job — allocate unassigned funds | | ynab-true-expenses | Embrace Your True Expenses — plan for irregular/annual costs | | ynab-overspending-triage | Roll With the Punches — find and fix overspending | | ynab-age-of-money | Age Your Money — check cash cushion and credit card float | | ynab-reconcile-cleanup | Weekly hygiene: reconciliation and category cleanup |

See docs/REMOTE_HOSTING.md for details.

Skills

Our MCP server gives Claude access to your YNAB budget. Our skills teach Claude YNAB's own best practices — some work standalone, some get sharper when connected. Together, they turn raw budget data into an actual coach.

The skills/ directory has 15 Claude Agent Skills: 7 that orchestrate this MCP server's tools into guided reviews, and 8 standalone coaching skills (getting started, debt payoff, irregular income, windfalls, emergency funds, and more) that work with or without this server connected. Every GitHub Release attaches them as downloadable zips — see skills/README.md for the full list and install instructions.

Development

# Run with hot reload
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Fix lint issues
npm run lint:fix

# Type check only
npm run typecheck

Testing with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Architecture

src/
├── index.ts              # Entry point (selects stdio or http transport)
├── server.ts             # Per-user server + tool registration
├── http.ts               # Express app for remote (Streamable HTTP) mode
├── crypto.ts             # AES-256-GCM at-rest token encryption
├── config/               # Environment configuration
├── auth/                 # Remote OAuth: MCP AS provider, YNAB client, sessions
├── storage/              # Pluggable storage (memory / sqlite / postgres)
├── services/             # Core services
│   ├── ynab-client.ts    # YNAB API wrapper with rate limiting
│   ├── rate-limiter.ts   # Token bucket rate limiter
│   ├── audit-log.ts      # Per-user write audit log
│   └── cache.ts          # In-memory TTL cache
├── tools/                # MCP tool implementations
│   ├── user/
│   ├── budgets/
│   ├── accounts/
│   ├── categories/
│   ├── payees/
│   ├── months/
│   ├── transactions/
│   ├── scheduled-transactions/
│   └── analytics/
└── utils/                # Helpers (currency, dates, errors)

Security

| Feature | Description | |---------|-------------| | Read-Only Default | Write operations disabled unless YNAB_READ_ONLY=false | | Token Security | Never commit your YNAB_ACCESS_TOKEN; use environment variables | | Input Validation | All tool parameters validated with Zod schemas | | Rate Limiting | Built-in protection against API quota exhaustion | | Audit Logging | All write operations logged for review |

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting: npm test && npm run lint
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• YNAB for their excellent budgeting platform and API
• Anthropic for Claude and the Model Context Protocol
• Model Context Protocol for the MCP specification

Related Projects

• YNAB API Documentation
• Model Context Protocol
• Claude Desktop