Provides comprehensive integration with YNAB (You Need A Budget) for managing personal finances, including tools for budget management, transaction operations, category organization, split transactions, scheduled transactions, and spending analytics with visualization capabilities.
YNAB MCP Server
MCP server for YNAB (You Need A Budget) integration, enabling AI assistants to help manage your budget.
Setup
- Install dependencies with - uv:
- Get your YNAB Personal Access Token: - Create a new Personal Access Token 
- Copy the token 
 
- Create - .envfile:
- Add your token to - .env:
Running the Server
Installing in Claude Code
Add to your Claude Code configuration:
Or add to .claude.json manually in the mcpServers section:
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_LEVELenvironment 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:
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:
- Call - prepare_split_for_matchingwith the existing transaction ID and desired splits
- The tool fetches the original transaction details and creates a new unapproved split transaction 
- Go to YNAB (web or mobile) and manually match the two transactions 
- 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
- Run the health check tool: - health_check
- Check that - YNAB_ACCESS_TOKENis set in your- .envfile
- Verify the token is valid at https://app.ynab.com/settings/developer 
- 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-Afterheaders
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- limitand- pageparameters)
Development
Running Tests
Install dev dependencies:
Run tests:
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 
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
Enables AI assistants to help manage your You Need A Budget (YNAB) finances through comprehensive budget operations. Supports account management, transaction handling, category budgeting, split transactions, scheduled payments, and spending analytics with robust error handling and automatic retry logic.