dgalarza/ynab-mcp-dgalarza

YNAB MCP Server

MCP server for YNAB (You Need A Budget) integration, enabling AI assistants to help manage your budget.

Setup

1. Install dependencies with uv:

uv sync

2. Get your YNAB Personal Access Token:

   • Go to https://app.ynab.com/settings/developer
   • Create a new Personal Access Token
   • Copy the token

3. Create .env file:

cp .env.example .env

4. Add your token to .env:

YNAB_ACCESS_TOKEN=your_token_here

Running the Server

uv run python -m ynab_mcp

Installing in Claude Code

Add to your Claude Code configuration:

claude mcp add ynab -- uv --directory /path/to/ynab-mcp run python -m ynab_mcp

Or add to .claude.json manually in the mcpServers section:

{
  "ynab": {
    "type": "stdio",
    "command": "uv",
    "args": ["--directory", "/home/your-user/Code/ynab-mcp", "run", "python", "-m", "ynab_mcp"],
    "env": {}
  }
}

Available Tools

Health & Diagnostics

• health_check - Check server health and YNAB API connectivity

Account Management

• get_accounts - Get all accounts for a budget

Category & Budget Management

• get_category - Get a single category with full details including goal information
• get_categories - Get all categories for a budget (lightweight list)
• get_budget_summary - Get budget summary for a specific month
• update_category - Update category properties (name, note, group, or goal target)
• update_category_budget - Update the budgeted amount for a category in a specific month
• move_category_funds - Move funds from one category to another

Transaction Management

• get_transaction - Get a single transaction with full details including subtransactions
• get_transactions - Get transactions with pagination and filtering (date range, account, category, limit, page)
• search_transactions - Search transactions by text in payee name or memo
• create_transaction - Create a new transaction
• update_transaction - Update an existing transaction (⚠️ cannot add/modify splits on existing transactions)
• get_unapproved_transactions - Get all unapproved transactions that need review

Split Transaction Management

• create_split_transaction - Create a new transaction split across multiple categories
• prepare_split_for_matching - Split an existing imported transaction by creating a matching split for manual reconciliation in YNAB UI

Scheduled Transactions

• get_scheduled_transactions - List all scheduled transactions
• create_scheduled_transaction - Create future/recurring transactions
• delete_scheduled_transaction - Delete scheduled transactions

Analytics & Reporting

• get_category_spending_summary - Get spending summary with optional terminal graph visualization
• compare_spending_by_year - Year-over-year spending comparison with optional graph

Features

Robust Error Handling

• Custom exception classes for different error types
• Automatic retry logic with exponential backoff
• Rate limit detection and handling (respects Retry-After headers)
• Comprehensive logging (configurable via LOG_LEVEL environment variable)

Performance & Reliability

• HTTP connection pooling for better performance
• Input validation on all parameters
• Timeout configuration (30s default)
• Milliunits conversion handled automatically

Split Transaction Support

Split transactions allow you to allocate a single transaction across multiple categories (e.g., splitting a grocery store purchase into "Groceries" and "Household Items").

Creating New Split Transactions:

create_split_transaction(
  budget_id="last-used",
  account_id="account-id",
  date="2025-10-06",
  amount=-80.00,
  subtransactions='[{"amount": -50.00, "category_id": "groceries-id", "memo": "Food"}, {"amount": -30.00, "category_id": "household-id", "memo": "Supplies"}]'
)

Splitting Existing Imported Transactions: Due to YNAB API limitations, you cannot directly modify an existing transaction to add splits. Instead, use prepare_split_for_matching:

1. Call prepare_split_for_matching with the existing transaction ID and desired splits
2. The tool fetches the original transaction details and creates a new unapproved split transaction
3. Go to YNAB (web or mobile) and manually match the two transactions
4. YNAB merges them into one split transaction, preserving the bank import connection

Important Limitations:

• Cannot add or update subtransactions on existing transactions via the API
• Cannot convert a regular transaction into a split transaction directly
• Once created, subtransactions cannot be modified via the API
• Split transaction dates and amounts cannot be changed after creation

Analytics & Visualization

• Server-side spending aggregation to reduce context usage
• Optional terminal-based graph visualization using termgraph
• Year-over-year spending comparisons
• Monthly spending summaries

Configuration

Environment Variables

• YNAB_ACCESS_TOKEN (required) - Your YNAB Personal Access Token
• LOG_LEVEL (optional) - Logging level (DEBUG, INFO, WARNING, ERROR, default: INFO)

Troubleshooting

MCP Server Not Connecting

1. Run the health check tool: health_check
2. Check that YNAB_ACCESS_TOKEN is set in your .env file
3. Verify the token is valid at https://app.ynab.com/settings/developer
4. Check logs with LOG_LEVEL=DEBUG

Rate Limit Errors

The YNAB API has a rate limit of 200 requests per hour. The server automatically:

• Detects 429 (rate limit) responses
• Retries with exponential backoff
• Respects Retry-After headers

If you consistently hit rate limits, consider:

• Using analytics tools (get_category_spending_summary, compare_spending_by_year) instead of fetching all transactions
• Reducing the frequency of requests
• Caching results when possible

Large Response Sizes

For queries spanning long time periods, use:

• get_category_spending_summary - Returns aggregated summary instead of all transactions
• compare_spending_by_year - Returns year-over-year totals instead of individual transactions
• Pagination with get_transactions (use limit and page parameters)

Development

Running Tests

Install dev dependencies:

uv sync --extra dev

Run tests:

uv run pytest tests/ -v

Code Quality

The codebase includes:

• Input validation on all parameters
• Custom exception classes for proper error handling
• Comprehensive logging
• Type hints with from __future__ import annotations
• Connection pooling for HTTP requests
• Automatic retry logic for transient failures