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
.env
file:
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 informationget_categories
- Get all categories for a budget (lightweight list)get_budget_summary
- Get budget summary for a specific monthupdate_category
- Update category properties (name, note, group, or goal target)update_category_budget
- Update the budgeted amount for a category in a specific monthmove_category_funds
- Move funds from one category to another
Transaction Management
get_transaction
- Get a single transaction with full details including subtransactionsget_transactions
- Get transactions with pagination and filtering (date range, account, category, limit, page)search_transactions
- Search transactions by text in payee name or memocreate_transaction
- Create a new transactionupdate_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 categoriesprepare_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 transactionscreate_scheduled_transaction
- Create future/recurring transactionsdelete_scheduled_transaction
- Delete scheduled transactions
Analytics & Reporting
get_category_spending_summary
- Get spending summary with optional terminal graph visualizationcompare_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:
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_matching
with the existing transaction ID and desired splitsThe 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 TokenLOG_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_TOKEN
is set in your.env
fileVerify 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-After
headers
If you consistently hit rate limits, consider:
Using analytics tools (
get_category_spending_summary
,compare_spending_by_year
) instead of fetching all transactionsReducing 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 transactionscompare_spending_by_year
- Returns year-over-year totals instead of individual transactionsPagination with
get_transactions
(uselimit
andpage
parameters)
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.