Skip to main content
Glama
YNAB MCP Server

YNAB MCP Server

by a1athrop

YNAB MCP Server

MCP server for YNAB (You Need A Budget) — manage budgets, accounts, categories, and transactions through Claude.

Tools

Core (daily budget management)

Tool

Description

get_budgets

List all budgets

get_accounts

List accounts with balances

get_categories

Category groups with budgeted/activity/balance

get_payees

List payees (for resolving names to IDs)

get_month

Monthly overview with per-category breakdown

get_transactions

Search transactions by date/account/category/payee

create_transaction

Add a new transaction

update_month_category

Change budgeted amount for a category

Extended (weekly/occasional)

Tool

Description

update_transaction

Edit existing transaction fields

delete_transaction

Delete a transaction

create_transactions_bulk

Create multiple transactions from JSON

get_scheduled_transactions

View recurring/upcoming bills

create_account

Add a new account

get_budget_months

Historical month list for trends

update_category

Change category name, note, or goal

Related MCP server: YNAB Assistant

Setup

1. Get a YNAB Personal Access Token

Go to YNAB Settings > Developer Settings and create a Personal Access Token.

2. Configure environment

cp .env.example .env
# Edit .env and set YNAB_ACCESS_TOKEN

3. Run locally

# stdio transport (Claude Desktop / Claude Code)
uv run server.py

# HTTP transport (Claude.ai connector / remote access)
uv run server.py --transport streamable-http

4. Claude Desktop configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ynab": {
      "command": "uv",
      "args": ["run", "/path/to/ynab-mcp/server.py"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Deployment (Railway)

  1. Push this repo to GitHub

  2. Create a new Railway project and connect the repo

  3. Set environment variables in Railway:

    • YNAB_ACCESS_TOKEN — your YNAB Personal Access Token

    • YNAB_DEFAULT_BUDGET_ID — (optional) default budget UUID or "last-used"

    • MCP_BEARER_TOKEN — (optional) secure the MCP endpoint

  4. Railway auto-deploys on push to main

The server reads the PORT environment variable (set automatically by Railway).

Multi-User Support

Set per-user tokens to give each person their own connector URL:

YNAB_TOKEN_ADAM=adams-token
YNAB_TOKEN_SARAH=sarahs-token

URL routing:

  • /adam/mcp — uses YNAB_TOKEN_ADAM

  • /sarah/mcp — uses YNAB_TOKEN_SARAH

  • /mcp — uses YNAB_ACCESS_TOKEN (default)

Currency Format

YNAB uses milliunits (1/1000 of a currency unit):

  • $10.00 = 10000 milliunits

  • -$5.50 = -5500 milliunits

All tool responses include both raw milliunit values and formatted display strings (e.g., balance and balance_display).

Rate Limits

YNAB allows 200 requests per hour per access token. The server returns friendly error messages when rate limited (HTTP 429).

Available Tools

15 tools
create_accountA

Create a new account in a budget.

Args: name: Account name (e.g., "Chase Checking"). type: Account type. One of: checking, savings, cash, creditCard, lineOfCredit, otherAsset, otherLiability, mortgage, autoLoan, studentLoan, personalLoan, medicalDebt, otherDebt. balance: Starting balance in milliunits (e.g., 100000 = $100.00). budget_id: Budget ID (uses default if omitted).

Returns: Created account details with id, name, type, and balance.

Inputs: name (required), type (required), balance (required), budget_id. Returns: result

create_transactionA

Create a new transaction.

Args: account_id: The account UUID to create the transaction in. date: Transaction date in YYYY-MM-DD format. amount: Amount in milliunits (negative for outflows, positive for inflows). Example: -50000 = -$50.00 outflow, 150000 = $150.00 inflow. payee_name: Name of payee (creates new payee if doesn't exist). Use this OR payee_id. payee_id: UUID of existing payee. Use this OR payee_name. category_id: UUID of the budget category. Omit when using subtransactions (each sub has its own). memo: Transaction memo. cleared: Cleared status: "cleared", "uncleared", or "reconciled". Defaults to "cleared". approved: Whether the transaction is approved. Defaults to True. flag_color: Optional flag: red, orange, yellow, green, blue, purple. subtransactions: Array of subtransaction objects for split transactions. Each item: {"amount": int, "category_id": "uuid", "memo": "text", "payee_id": "uuid", "payee_name": "text"}. Only amount and category_id are required per sub. The sub amounts must sum to the parent amount. When using subtransactions, omit category_id on the parent (it becomes a split). budget_id: Budget ID (uses default if omitted).

Returns: Created transaction details with id, date, amount, payee, category, and subtransactions.

Inputs: account_id (required), date (required), amount (required), payee_name, +8 more. Returns: result

create_transactions_bulkA

Create multiple transactions at once from a JSON string.

The JSON should contain a "transactions" array where each item has: account_id (required), date (required), amount (required in milliunits), and optionally: payee_name, payee_id, category_id, memo, cleared, approved, flag_color, subtransactions (array of {amount, category_id, memo, payee_id, payee_name}).

Args: transactions_json: JSON string with a "transactions" array. budget_id: Budget ID (uses default if omitted).

Returns: Summary of created and duplicate transactions.

Inputs: transactions_json (required), budget_id. Returns: result

delete_transactionB

Delete a transaction.

Args: transaction_id: The transaction UUID to delete. budget_id: Budget ID (uses default if omitted).

Returns: Confirmation of deletion.

Inputs: transaction_id (required), budget_id. Returns: result

get_accountsA

List all accounts in a budget with balances.

Args: budget_id: Budget ID (uses default if omitted).

Returns: List of accounts with name, type, balance, cleared_balance, on_budget, and closed status.

Inputs: budget_id. Returns: result

get_budget_monthsA

List all months in a budget with summary data.

Useful for trend analysis — see how income, spending, and budgeting have changed over time.

Args: budget_id: Budget ID (uses default if omitted).

Returns: List of months with income, budgeted, activity, to_be_budgeted, age_of_money.

Inputs: budget_id. Returns: result

get_budgetsA

List all budgets the user has access to.

Args: include_accounts: If True, include account summaries for each budget.

Returns: List of budgets with id, name, last_modified_on, and currency format.

Inputs: include_accounts. Returns: result

get_categoriesA

List all category groups and categories with budgeted/activity/balance for the current month.

Args: budget_id: Budget ID (uses default if omitted).

Returns: Category groups with nested categories showing budgeted, activity, balance, and goal info.

Inputs: budget_id. Returns: result

get_monthA

Get a monthly budget summary with category breakdowns.

Args: month: Month in YYYY-MM-DD format (first of month, e.g., "2026-02-01"). Defaults to current month. budget_id: Budget ID (uses default if omitted).

Returns: Month overview: income, budgeted, activity, to_be_budgeted, age_of_money, plus per-category details.

Inputs: month, budget_id. Returns: result

get_payeesB

List all payees in a budget.

Args: budget_id: Budget ID (uses default if omitted).

Returns: List of payees with id and name.

Inputs: budget_id. Returns: result

get_scheduled_transactionsB

List all scheduled (recurring) transactions.

Args: budget_id: Budget ID (uses default if omitted).

Returns: List of scheduled transactions with frequency, next date, amount, payee, category.

Inputs: budget_id. Returns: result

get_transactionsA

Search and list transactions with optional filters.

Args: budget_id: Budget ID (uses default if omitted). since_date: Only return transactions on or after this date (YYYY-MM-DD). before_date: Only return transactions before this date (YYYY-MM-DD). Server-side filter. Use with since_date for a date range, e.g. since_date="2024-02-01", before_date="2024-03-01" for all February 2024 transactions. type: Filter by "uncategorized" or "unapproved". account_id: Filter to a specific account. category_id: Filter to a specific category. payee_id: Filter to a specific payee. max_results: Maximum transactions to return (default 200).

Returns: List of transactions with date, amount, payee, category, memo, cleared status. Includes truncated flag and total_available count when results are capped.

Inputs: budget_id, since_date, before_date, type, +4 more. Returns: result

update_categoryB

Update a category's name, note, or goal target.

Args: category_id: The category UUID. name: New category name. note: New category note. goal_target: New goal target in milliunits (e.g., 500000 = $500.00). budget_id: Budget ID (uses default if omitted).

Returns: Updated category details.

Inputs: category_id (required), name, note, goal_target, +1 more. Returns: result

update_month_categoryA

Update the budgeted amount for a category in a specific month.

Use this to move money between categories or adjust budget allocations.

Args: category_id: The category UUID to update. budgeted: New budgeted amount in milliunits (e.g., 50000 = $50.00). month: Month in YYYY-MM-DD format (first of month). Defaults to current month. budget_id: Budget ID (uses default if omitted).

Returns: Updated category with new budgeted amount, activity, and balance.

Inputs: category_id (required), budgeted (required), month, budget_id. Returns: result

update_transactionA

Update an existing transaction.

Args: transaction_id: The transaction UUID to update. account_id: Move to a different account. date: New date (YYYY-MM-DD). amount: New amount in milliunits. payee_name: New payee name. payee_id: New payee UUID. category_id: New category UUID. memo: New memo. cleared: New cleared status: "cleared", "uncleared", or "reconciled". approved: New approved status. flag_color: New flag color: red, orange, yellow, green, blue, purple. subtransactions: Array of subtransaction objects to convert this into a split transaction. Each item: {"amount": int, "category_id": "uuid", "memo": "text", "payee_id": "uuid", "payee_name": "text"}. Only amount and category_id are required per sub. The sub amounts must sum to the parent amount. When adding subtransactions, also provide the new parent amount if changing it. budget_id: Budget ID (uses default if omitted).

Returns: Updated transaction details.

Inputs: transaction_id (required), account_id, date, amount, +9 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool has a distinct purpose targeting specific resources and actions, such as create_account for accounts, get_transactions for listing, and update_month_category for budget adjustments. No significant overlap exists; even create_transaction and create_transactions_bulk are clearly differentiated by single vs. bulk operations.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern, using verbs like create, get, update, and delete paired with specific nouns like account, transaction, or category. This uniformity makes the tool set predictable and easy to navigate.

    Tool Count5/5

    With 15 tools, the server covers core budgeting operations comprehensively without being overwhelming. This count is well-suited for the domain, providing essential CRUD and query functions for accounts, transactions, budgets, categories, and payees.

    Completeness5/5

    The tool set offers complete coverage for personal finance management, including CRUD for accounts and transactions, budget and category management, payee handling, and month-level operations. No obvious gaps exist; agents can perform end-to-end budgeting workflows seamlessly.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to help manage your You Need A Budget (YNAB) finances through comprehensive budget operations. Supports account management, transaction handling, category budgeting, split transactions, scheduled payments, and spending analytics with robust error handling and automatic retry logic.
      21
      4
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with YNAB budgets through natural language. Supports managing accounts, categories, transactions, and budget months with 21 tools for comprehensive budget operations.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables interaction with You Need A Budget (YNAB) through their API, allowing users to manage budgets, accounts, categories, transactions, payees, and scheduled transactions through natural language.
      12
      23 npm
      2
      GPL 3.0
    • A
      license
      C
      quality
      C
      maintenance
      Exposes YNAB API endpoints as MCP tools, allowing AI assistants to manage budgets, accounts, transactions, and more through natural language.
      41
      198 PyPI
      100
      MIT