# 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
1. Get a YNAB Personal Access Token at https://app.youneedabudget.com/settings/developer
2. 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
