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.

Variable	Description	Default
YNAB_API_TOKEN	YNAB personal access token	required
YNAB_API_URL	Override the YNAB API base URL	YNAB default
YNAB_MCP_DATA_DIR	Directory for undo history storage	~/.ynab-mcp
YNAB_READ_ONLY	Disable all write operations (true/false/1/0)	false

Tools

Budgets

Tool	Description
list_budgets	List all budgets with metadata
get_budget_summary	Net worth, month totals, overspent categories, account summary
sync_budget_data	Force-refresh cached data from YNAB

Accounts

Tool	Description
get_accounts	List accounts with balances, filterable by type and on/off budget

Transactions

Tool	Description
search_transactions	Search with filters (dates, amounts, accounts, categories, payees, flags, cleared status) — supports multiple queries in one call
create_transactions	Batch create transactions with optional splits
update_transactions	Batch update existing transactions
delete_transactions	Batch delete transactions

Categories

Tool	Description
list_categories	Category group hierarchy with IDs and names
get_targets	Target details: type, amounts, underfunded, percent complete, cadence, and deadlines
get_monthly_budget	Month-level budgeted/activity/balance per category
set_category_budgets	Batch set budgeted amounts across categories and months
set_category_targets	Create or update category targets (monthly, weekly, by-date, etc.)

Spending Analysis

Tool	Description
get_spending_analysis	Spending aggregates grouped by category, payee, or both — with top-N ranking

Scheduled Transactions

Tool	Description
get_scheduled_transactions	List scheduled transactions with optional filters
create_scheduled_transactions	Batch create with frequency (daily, weekly, monthly, yearly, or one-time)
update_scheduled_transactions	Batch update scheduled transactions
delete_scheduled_transactions	Batch delete scheduled transactions

Smart Tools

Tool	Description
suggest_transaction_categories	Suggest categories for uncategorized transactions based on payee history and patterns
suggest_overspending_coverage	Suggest budget moves to cover overspent categories from surplus ones
suggest_budget_allocation	Priority-based allocation of unbudgeted funds across underfunded categories

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

Analysis & Diagnostics

Tool	Description
get_budget_health	Single-call budget diagnostic: overspending, target gaps, RTA, flags
get_spending_velocity	Mid-month spending pace per category vs budget
forecast_category_balances	End-of-month balance projections based on scheduled and past trends
get_spending_trends	Multi-month time series by category or payee
get_income_expense_summary	Income vs expense totals with savings rate
get_spending_breakdown	Spending by time granularity (daily, weekly, day-of-week)
detect_recurring_charges	Subscription and recurring charge detection from transaction history
detect_anomalies	Flag unusual transactions by amount, frequency, or category
diagnose_credit_card_debt	Trace credit card debt sources and suggest payoff strategies

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

Undo

Tool	Description
list_undo_history	List recorded undo entries
undo_operations	Undo one or more previous write operations by ID

Resources

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

URI	Topic
ynab://knowledge/terminology	Core YNAB concepts and terminology
ynab://knowledge/credit-cards	Credit card handling
ynab://knowledge/targets	Target types and behavior
ynab://knowledge/overspending	Overspending mechanics
ynab://knowledge/reconciliation	Reconciliation workflow
ynab://knowledge/api-quirks	API quirks and limitations

Prompts

Prompt	Description
monthly-review	Guided monthly budget review
spending-report	Spending report for a date range
triage-unapproved	Batch review and approve unapproved transactions
budget-optimization	Analyze budget for optimization opportunities
subscription-audit	Review recurring charges and manage subscriptions

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