YNAB MCP Server

Talk to your finances.

What is this?

YNAB (You Need A Budget) 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)

npm install -g ynab-mcp-server

From source

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):

export YNAB_API_TOKEN="your-token-here"

Claude Code

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):

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "ynab-mcp-server"],
      "env": {
        "YNAB_API_TOKEN": "${YNAB_API_TOKEN}"
      }
    }
  }
}

Manual usage

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