YNAB MCP Server

An MCP server for YNAB with batch operations, deterministic analysis tools, and robust undo support.

[!NOTE] AI Disclosure: This project was built with Claude Code and Cursor. It works and is tested, but the code is largely clanker-made.

Highlights

• 32 tools covering budgets, accounts, transactions, categories, targets, scheduled transactions, and spending analysis
• Deterministic analysis — budget health, spending trends, forecasts, anomaly detection, and more with no LLM sampling
• Batch operations — create, update, and delete multiple transactions or category assignments in a single call
• Undo support — every write operation is recorded and reversible
• Smart tools — transaction categorization, overspending coverage, and budget allocation suggestions using payee history and patterns
• Built-in knowledge base — YNAB methodology docs (credit cards, targets, overspending, reconciliation) served as MCP resources
• 5 workflow prompts — monthly reviews, spending reports, unapproved triage, budget optimization, and subscription audits
• Read-only mode — disable all write operations for safe exploration
• Efficient caching — delta sync with YNAB's server knowledge system minimizes API calls

Setup

Prerequisites

• Node.js >= 20
• A YNAB personal access token

Usage

Run directly with npx:

YNAB_API_TOKEN=your-token npx @maro-org/ynab-mcp

Or install globally:

npm install -g @maro-org/ynab-mcp
YNAB_API_TOKEN=your-token ynab-mcp

MCP Client Configuration

Add the server to your MCP client config. For example, in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@maro-org/ynab-mcp"],
      "env": {
        "YNAB_API_TOKEN": "your-token"
      }
    }
  }
}

For Cursor, add the same structure to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally.

Configuration

All configuration is done through environment variables.

Tools

Budgets

Accounts

Transactions

Categories

Spending Analysis

Scheduled Transactions

Smart Tools

These return structured actions that can be passed directly to update_transactions or set_category_budgets.

Analysis & Diagnostics

All analysis tools are deterministic -- no LLM sampling involved.

Undo

Resources

Knowledge base resources for YNAB methodology. Workflow prompts reference these automatically.

Prompts

Key Concepts

Currency units — All monetary amounts in tool inputs and outputs use standard currency units (e.g., 12.50), not YNAB's native milliunits. The server handles conversion automatically.

`budget_id` — Most tools accept an optional budget_id. Omit it or pass "last-used" to target the most recently accessed budget.

Undo — Every write operation records an undo entry. Use list_undo_history and undo_operations to review or revert changes.

Read-only mode — Set YNAB_READ_ONLY=true to block all write operations. Useful for exploring your budget safely or restricting an MCP client to read-only access.

Development

npm install
npm run dev        # run with tsx watch
npm run build      # compile TypeScript
npm test           # run tests (vitest)
npm run typecheck  # type-check without emitting
npm run lint       # lint with Biome
npm run ci         # typecheck + lint + test

License

MIT