Content
# YNAB MCP Server
Talk to your finances.
## What is this?
[YNAB (You Need A Budget)](https://ynab.com) is a popular budgeting app that helps you gain control of your money. This MCP server connects AI assistants to your YNAB data, giving you conversational access to:
- Your budgets and accounts
- Transaction history and patterns
- Category balances and spending insights
- Scheduled and recurring transactions
- Creating and managing transactions
- Updating category budgets
- Creating accounts
## Installation
### Via npx (recommended)
No installation required. Configure your Claude client to use npx directly (see below).
### Via npm (global)
```bash
npm install -g ynab-mcp-server
```
### From source
```bash
git clone https://github.com/jeangnc/ynab-mcp-server.git
cd ynab-mcp-server
make install
make build
```
## Configuration
First, set your YNAB API token in your shell profile (`~/.zshrc` or `~/.bashrc`):
```bash
export YNAB_API_TOKEN="your-token-here"
```
### Claude Code
```bash
claude mcp add ynab --scope user --env YNAB_API_TOKEN='${YNAB_API_TOKEN}' -- npx -y ynab-mcp-server
```
### Claude Desktop
Add to `~/.config/claude/claude_desktop_config.json` (Linux) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
```json
{
"mcpServers": {
"ynab": {
"command": "npx",
"args": ["-y", "ynab-mcp-server"],
"env": {
"YNAB_API_TOKEN": "${YNAB_API_TOKEN}"
}
}
}
}
```
### Manual usage
```bash
YNAB_API_TOKEN=$YNAB_API_TOKEN npx ynab-mcp-server
```
## Available Tools
### Read Tools
| Tool | Description |
|------|-------------|
| `list_budgets` | Get all budgets for the authenticated user. Returns budget names, IDs, and last modified dates. |
| `get_budget` | Get detailed information about a specific budget including accounts, categories, and settings. |
| `list_accounts` | Get all accounts for a budget. Returns account names, types, balances, and status. |
| `get_account` | Get detailed information about a specific account. |
| `list_categories` | Get all categories for a budget, grouped by category group. Includes budgeted amounts and activity. |
| `get_category` | Get detailed information about a specific category including current month data. |
| `list_transactions` | Get transactions for a budget. Supports filtering by date, type, category, payee, and account. |
| `get_transaction` | Get detailed information about a specific transaction. |
| `list_payees` | Get all payees for a budget. |
| `list_scheduled_transactions` | Get all scheduled/recurring transactions for a budget. |
| `list_months` | Get all budget months. Returns month summaries with income, budgeted, and activity totals. |
| `get_month` | Get detailed budget information for a specific month including all category balances. |
### Write Tools
| Tool | Description |
|------|-------------|
| `create_transaction` | Create a new transaction. Amount should be negative for expenses and positive for income. |
| `update_transaction` | Update an existing transaction. Only provide the fields you want to change. |
| `delete_transaction` | Delete an existing transaction. |
| `update_category_budget` | Update the budgeted amount for a category in a specific month. |
| `create_account` | Create a new account in the budget. |
| `get_scheduled_transaction` | Get detailed information about a specific scheduled transaction. |
| `create_scheduled_transaction` | Create a new scheduled/recurring transaction. Date must be in the future (max 5 years). |
| `update_scheduled_transaction` | Update an existing scheduled transaction. Only provide fields you want to change. |
| `delete_scheduled_transaction` | Delete an existing scheduled transaction. |
| `update_payee` | Update a payee's name. The name must be a maximum of 500 characters. |
### History Tools
| Tool | Description |
|------|-------------|
| `list_history` | List recent write operations with their IDs for undo. Operations are listed in reverse chronological order (newest first). |
| `get_history_entry` | Get detailed information about a specific history entry including before/after state. |
| `undo_operation` | Revert a previous write operation by its history entry ID. |
## History & Undo
The server tracks all write operations (transactions, scheduled transactions, category budgets, payees, and accounts) and allows you to undo them.
### How it works
- All write operations are automatically recorded to `~/.ynab-mcp-history.json`
- History persists across server restarts
- Up to 100 operations are retained (oldest are automatically removed)
- Use `list_history` to see recent operations and their IDs
- Use `undo_operation` with an entry ID to revert a change
### Supported undo operations
| Operation | Undo Action |
|-----------|-------------|
| Create transaction | Deletes the created transaction |
| Update transaction | Restores to previous state |
| Delete transaction | Recreates the transaction (new ID) |
| Create scheduled transaction | Deletes the created scheduled transaction |
| Update scheduled transaction | Restores to previous state |
| Delete scheduled transaction | Recreates the scheduled transaction (new ID) |
| Update category budget | Restores previous budgeted amount |
| Update payee | Restores previous name |
| Create account | **Cannot be undone** (YNAB API limitation) |
### Limitations
- **Account creation cannot be undone**: The YNAB API does not support deleting accounts
- **Recreated transactions get new IDs**: When undoing a delete, the transaction is recreated with a new ID
- **External changes**: If data is modified outside the MCP server, undo may fail or produce unexpected results
- **Old history entries**: Very old entries may reference entities that no longer exist
## Makefile Commands
```
make install # Install dependencies
make build # Compile TypeScript
make run # Run compiled server
make dev # Run TypeScript directly
make clean # Remove build artifacts
```
