Skip to main content
Glama
Maronato

YNAB MCP Server

by Maronato
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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

Related MCP server: YNAB Assistant

Setup

Prerequisites

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

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
16Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Maronato/ynab-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server