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```bash
git clone https://github.com/wg-whm/ynab-mcp-server.git
cd ynab-mcp-server
pip install .
Or with uv:```bash
uv pip install .
Setup
-
Get a YNAB Personal Access Token at https://app.youneedabudget.com/settings/developer
-
Store the token:```bash
Option A: OS keyring (recommended)
ynab-mcp store-token
Option B: Environment variable
export YNAB_API_TOKEN="your-token-here"
3. Verify:```bash
ynab-mcp check-token
Usage
With Claude Code / MCP Clients
Add to your MCP config:```json
{
"mcpServers": {
"ynab": {
"command": "ynab-mcp"
}
}
}
### Direct```bash
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