YNAB MCP Server
A minimal, auditable MCP (Model Context Protocol) server for YNAB budget management. Designed for local AI assistants that need to read and modify YNAB budgets.
Why This Exists
Use a local LLM for financial coaching while keeping sensitive context (goals, reasoning, life circumstances) off cloud servers. Only structured API commands go to YNAB.
Features
- Read: Budgets, accounts, categories, transactions, payees
- Write: Create transactions, move money between categories
- Secure: Token stored in OS keyring, never logged or transmitted elsewhere
Installation
git clone https://github.com/wg-whm/ynab-mcp-server.git
cd ynab-mcp-server
pip install .
Or with uv:
uv pip install .
Setup
-
Get a YNAB Personal Access Token at https://app.youneedabudget.com/settings/developer
-
Store the token:
# Option A: OS keyring (recommended)
ynab-mcp store-token
# Option B: Environment variable
export YNAB_API_TOKEN="your-token-here"
- Verify:
ynab-mcp check-token
Usage
With Claude Code / MCP Clients
Add to your MCP config:
{
"mcpServers": {
"ynab": {
"command": "ynab-mcp"
}
}
}
Direct
ynab-mcp run
Available Tools
| Tool | Description | Modifies Data |
|---|---|---|
ynab_get_budgets | List all budgets | No |
ynab_get_accounts | List accounts with balances | No |
ynab_get_categories | List categories with budgeted/spent/available | No |
ynab_get_transactions | List transactions (filterable) | No |
ynab_get_month_summary | Month overview with overspent warnings | No |
ynab_get_payees | List all payees | No |
ynab_move_money | Move money between categories | Yes |
ynab_create_transaction | Create new transaction | Yes |
ynab_update_transaction | Update existing transaction | Yes |
Security
What stays local:
- Your goals and motivations
- AI coaching responses
- Conversation history
- Life context you share
What goes to YNAB API:
- Structured API calls (get categories, create transaction, etc.)
- Same data YNAB already has
Audit points:
src/ynab_mcp_server/api.py- All API communication (~300 lines)- Only endpoint:
https://api.ynab.com/v1 - Token retrieved from keyring/env, never logged
License
MIT