# ynab-mcpb [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/dizzlkheinz/ynab-mcpb  
**GitHub Stars:** 9  
**npm Downloads (last month):** 1081  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ynab-mcpb

## Description
MCP server for YNAB (You Need A Budget) — budgets, accounts, transactions, categories

## Tools
Capabilities this server exposes over MCP:

- **ynab_list_budgets** — List all YNAB budgets for the authenticated user.

Args:
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: budgets[], cached, cache_info

Examples:
  - List all budgets: call with no args

Errors:
  - "UNAUTHORIZED" → YNAB token expired or invalid
- **ynab_get_budget** — Get summary information for a specific YNAB budget.

Args:
  - budget_id (string, required): Budget UUID.
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: budget (id, name, currency_format, accounts_count, categories_count, payees_count, months_count)

Examples:
  - Get budget details: set budget_id to the UUID from ynab_list_budgets

Errors:
  - "Budget not found" → invalid or inaccessible budget_id
- **ynab_list_payees** — List all payees for a budget with pagination.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - limit (int, optional): Max results per page. Default: 50.
  - offset (int, optional): Zero-based offset for pagination. Default: 0.
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: payees[], total_count, returned_count, offset, has_more, next_offset, cached, cache_info

Examples:
  - List all payees: call with no args
  - Page 2: set limit=50, offset=50

Errors:
  - "No default budget set" → run ynab_set_default_budget first
- **ynab_get_payee** — Get details for a specific payee.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - payee_id (string, required): Payee UUID.
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: payee (id, name, transfer_account_id, deleted), cached, cache_info

Errors:
  - "No default budget set" → run ynab_set_default_budget first
  - "Payee not found" → invalid payee_id
- **ynab_list_categories** — List all budget categories for a budget with pagination.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - limit (int, optional): Max results per page. Default: 50.
  - offset (int, optional): Zero-based offset for pagination. Default: 0.
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: categories[], category_groups[], total_count, returned_count, offset, has_more, next_offset, cached, cache_info

Examples:
  - List categories (default budget): call with no args
  - Page 2: set limit=50, offset=50

Errors:
  - "No default budget set" → run ynab_set_default_budget first
- **ynab_get_category** — Get current month details for a specific budget category.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - category_id (string, optional): Category UUID.
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: category (id, name, budgeted, activity, balance, goal_type, goal_target, goal_percentage_complete), cached, cache_info

Errors:
  - "No default budget set" → run ynab_set_default_budget first
  - "Category not found" → invalid category_id
- **ynab_update_category** — Update the budgeted amount for a category in the current month.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - category_id (string, required): Category UUID.
  - budgeted_decimal (number, preferred): New funding amount in decimal currency units.
  - budgeted_milliunits (int, alternative): Explicit raw YNAB milliunits.
  - budgeted (int, deprecated): Backward-compatible alias for budgeted_milliunits.
  - dry_run (boolean, optional): Preview without saving. Default: false.

Returns: updated category with new budgeted, activity, balance.

Examples:
  - Budget $100: set budgeted_decimal=100.00
  - Already-converted data: set budgeted_milliunits=100000
  - Dry run: set dry_run=true

Errors:
  - "No default budget set" → run ynab_set_default_budget first

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.
- **ynab_list_accounts** — List all accounts for a budget.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - limit (int, optional): Max results per page. Default: 50.
  - offset (int, optional): Zero-based offset for pagination. Default: 0.
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: accounts[], total_count, returned_count, offset, has_more, next_offset, cached, cache_info

Examples:
  - List all accounts (default budget): call with no args
  - Page 2: set limit=20, offset=20

Errors:
  - "No default budget set" → run ynab_set_default_budget first
  - "UNAUTHORIZED" → YNAB token expired
- **ynab_get_account** — Get details for a single account including current balance.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - account_id (string, required): Account UUID.
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: account (id, name, type, balance, cleared_balance, uncleared_balance, on_budget, closed), cached, cache_info

Errors:
  - "No default budget set" → run ynab_set_default_budget first
  - "Account not found" → invalid account_id
- **ynab_create_account** — Create a new account in a YNAB budget.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - name (string, required): Account name.
  - type (string, required): One of: checking, savings, creditCard, cash, lineOfCredit, otherAsset, otherLiability.
  - balance (number, optional): Opening balance in dollars. Default: 0.
  - dry_run (boolean, optional): Preview the request without creating. Default: false.

Returns: account object with id, name, type, balance fields.

Examples:
  - Create checking account: set name="My Checking", type="checking"
  - Dry run: set dry_run=true to preview without saving

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.
- **ynab_get_month** — Get full budget data for a specific month including all category balances.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - month (string, required): Month in YYYY-MM-DD format (use first day, e.g. "2025-01-01").
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: month (month, income, budgeted, activity, to_be_budgeted, age_of_money, categories[]), cached, cache_info

Examples:
  - Get January 2025: set month="2025-01-01"

Errors:
  - "No default budget set" → run ynab_set_default_budget first
- **ynab_list_months** — List summary data for all budget months with pagination.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - limit (int, optional): Max results per page. Default: 50.
  - offset (int, optional): Zero-based offset for pagination. Default: 0.
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: months[], total_count, returned_count, offset, has_more, next_offset, cached, cache_info

Examples:
  - List recent months: call with no args, months are newest-first
  - Page 2: set limit=12, offset=12

Errors:
  - "No default budget set" → run ynab_set_default_budget first
- **ynab_list_transactions** — List transactions for a budget with optional filtering and pagination.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - account_id (string, optional): Filter by account.
  - category_id (string, optional): Filter by category.
  - since_date (string, optional): ISO date (YYYY-MM-DD) to filter transactions on or after.
  - type (string, optional): "uncategorized" or "unapproved".
  - cleared (string, optional): "cleared", "uncleared", or "reconciled".
  - limit (int, optional): Max results per page. Default: 50.
  - offset (int, optional): Zero-based offset for pagination. Default: 0.
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: transactions[], total_count, returned_count, offset, has_more, next_offset, cached, cache_info

Examples:
  - All transactions: call with no args (uses default budget)
  - Filter by account: set account_id
  - Last 30 days: set since_date to 30 days ago
  - Page 2: set limit=50, offset=50

Errors:
  - "No default budget set" → run ynab_set_default_budget first
  - Large result → use ynab_export_transactions to save to file
- **ynab_export_transactions** — Export all transactions for a budget to a local JSON file.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - account_id (string, optional): Filter by account.
  - since_date (string, optional): ISO date (YYYY-MM-DD) to filter transactions on or after.

Returns: file_path, transaction_count, file_size_kb

Examples:
  - Export all transactions: call with no args
  - Export account: set account_id

Errors:
  - "No default budget set" → run ynab_set_default_budget first
- **ynab_get_transaction** — Get full details for a single transaction by ID.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - transaction_id (string, required): Transaction UUID.
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: transaction (id, date, amount, memo, cleared, approved, account_id, payee_name, category_name, subtransactions), cached, cache_info

Errors:
  - "No default budget set" → run ynab_set_default_budget first
  - "Transaction not found" → invalid transaction_id
- **ynab_create_transaction** — Create a single transaction in YNAB.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - account_id (string, required): Account UUID.
  - amount_decimal (number, preferred): Amount in decimal currency units (for example, -50.00). Negative for expenses.
  - amount_milliunits (int, alternative): Explicit raw YNAB milliunits (for example, -50000).
  - amount (int, deprecated): Backward-compatible alias for amount_milliunits. Values are never guessed by magnitude.
  - date (string, required): ISO date YYYY-MM-DD.
  - payee_name (string, optional): Payee name (creates new payee if not found).
  - payee_id (string, optional): Existing payee UUID (alternative to payee_name).
  - category_id (string, optional): Category UUID.
  - memo (string, optional): Memo text.
  - cleared (string, optional): "cleared", "uncleared", or "reconciled". Default: "uncleared".
  - approved (boolean, optional): Mark as approved. Default: false.
  - flag_color (string, optional): Transaction flag color ("red", "orange", "yellow", "green", "blue", "purple").
  - dry_run (boolean, optional): Preview without saving. Default: false.
  - subtransactions (array, optional): Manual split lines. Each entry uses exactly one of amount_decimal, amount_milliunits, or deprecated amount, plus optional "memo", "category_id", "payee_id", and "payee_name".

Use "subtransactions" for manual split transactions. Use "ynab_create_receipt_split_transaction" when you have itemized receipt data and want proportional tax allocation handled for you.
Advanced: "import_id" is supported, but it is intentionally not part of normal guidance. Usually omit it if you want the transaction to remain eligible for later bank-import matching.

Returns: the created transaction, including split lines and explicit amount_milliunits.

Examples:
  - $50 expense: set amount_decimal=-50.00
  - Already-converted data: set amount_milliunits=-50000

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.
- **ynab_create_transactions** — Create 1–100 transactions in a single batch with duplicate detection and dry-run support.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - transactions (array, required): Up to 100 transaction objects. Each requires account_id, date, and exactly one of amount_decimal (preferred), amount_milliunits, or deprecated amount.
  - dry_run (boolean, optional): Validate without saving. Default: false.

Returns: summary (created, duplicates, failed), results[], transactions[].

Examples:
  - Dry run first: set dry_run=true to validate before committing
  - If you explicitly want YNAB-side duplicate import detection, set import_id on each transaction

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.
- **ynab_create_receipt_split_transaction** — Create a split transaction from itemized receipt data with proportional tax allocation.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - account_id (string, required): Account UUID.
  - payee_name (string, required): Store/payee name.
  - receipt_total (number, required): Total amount in dollars (positive).
  - receipt_tax (number, required): Tax amount in dollars (0 if none).
  - categories (array, required): Category groups with items. Each item needs name, amount.
  - date (string, optional): ISO date. Default: today.
  - memo (string, optional): Memo applied to the parent transaction.
  - receipt_subtotal (number, optional): Pre-tax subtotal for validation.
  - cleared (string, optional): "cleared", "uncleared", or "reconciled". Default: "uncleared".
  - approved (boolean, optional): Mark as approved. Default: false.
  - flag_color (string, optional): Transaction flag color ("red", "orange", "yellow", "green", "blue", "purple").
  - dry_run (boolean, optional): Preview subtransactions without saving. Default: false.

Use this helper when you have receipt line items and want tax allocated across categories automatically. For generic manual split transactions without receipt/tax logic, use "ynab_create_transaction" with "subtransactions".

Returns: transaction with subtransactions and receipt_summary.

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.
- **ynab_update_transaction** — Update fields on an existing YNAB transaction.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - transaction_id (string, required): Transaction UUID to update.
  - amount_decimal (number, preferred): New amount in decimal currency units.
  - amount_milliunits (int, alternative): Explicit raw YNAB milliunits.
  - amount (int, deprecated): Backward-compatible alias for amount_milliunits.
  - date (string, optional): New date YYYY-MM-DD.
  - payee_name / payee_id (string, optional): New payee.
  - category_id (string, optional): New category UUID.
  - memo (string, optional): New memo.
  - cleared (string, optional): "cleared", "uncleared", or "reconciled".
  - approved (boolean, optional): Approval status.
  - subtransactions (array, optional): Convert a non-split transaction into a split. Supply the parent amount and split lines using amount_decimal, amount_milliunits, or deprecated amount; split amounts must sum to the parent and category_id must be omitted on the parent. YNAB does not support replacing lines on an existing split.
  - dry_run (boolean, optional): Preview without saving.

Returns: the updated transaction, including split lines and explicit amount_milliunits.

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.
- **ynab_update_transactions** — Update 1–100 transactions in a single batch with dry-run preview.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - transactions (array, required): Up to 100 objects, each requires id plus fields to update. Amount updates use one of amount_decimal (preferred), amount_milliunits, or deprecated amount. A non-split transaction can be converted to a split by supplying the parent amount plus subtransactions that sum to it; YNAB does not support replacing lines on an existing split.
  - dry_run (boolean, optional): Preview changes without saving. Default: false.

Returns: summary (updated, failed), results[], transactions[].

Examples:
  - Dry run: set dry_run=true to preview before/after for first 10 items

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.
- **ynab_delete_transaction** — Delete a transaction from YNAB. This action is irreversible.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - transaction_id (string, required): Transaction UUID to delete.
  - dry_run (boolean, optional): Preview without deleting. Default: false.

Returns: the deleted transaction with its ID and deletion status.

Errors:
  - "Transaction not found" → invalid transaction_id

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.
- **ynab_list_scheduled_transactions** — List scheduled transactions with delta caching and pagination. Amounts are returned in decimal currency and explicit milliunits.
- **ynab_get_scheduled_transaction** — Get one scheduled transaction by ID.
- **ynab_create_scheduled_transaction** — Create a recurring scheduled transaction. Prefer amount_decimal; amount_milliunits is available for already-converted values.

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.
- **ynab_update_scheduled_transaction** — Update selected fields on a scheduled transaction.

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.
- **ynab_delete_scheduled_transaction** — Delete a scheduled transaction.

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.
- **ynab_analyze_spending** — Deterministically calculate income, spending, and net totals for an inclusive date range, grouped by category, payee, account, week, or month. Aggregates always use the complete fetched period before grouping.
- **ynab_compare_spending_periods** — Deterministically compare two complete spending periods and calculate total and per-group differences.
- **ynab_compare_transactions** — Compare bank CSV transactions with YNAB transactions to find missing or mismatched entries.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - account_id (string, required): Account UUID to compare against.
  - csv_file_path or csv_data (string, required): Bank export file path or inline CSV text.
  - statement_start_date (string, optional): Filter comparison window start date (YYYY-MM-DD).
  - statement_date (string, optional): Filter comparison window end date (YYYY-MM-DD).

Returns: comparison report with matched, unmatched_bank, unmatched_ynab transactions.
- **ynab_reconcile_account** — Guided account reconciliation: match bank CSV transactions to YNAB, detect discrepancies, and optionally execute bulk create/update/unclear operations.

Args:
  - budget_id (string, optional): Budget UUID. Omit to use the default budget.
  - account_id (string, required): Account UUID to reconcile.
  - csv_file_path or csv_data (string, required): Bank export file path or inline CSV text.
  - statement_balance (number, required): Ending balance from the bank statement (dollars).
      For credit cards and other liability accounts, pass a negative value (e.g. -6143.27 means you owe $6,143.27).
  - statement_end_date (string, optional): Statement closing date (YYYY-MM-DD). Filters CSV and triggers balance verification. Auto-detected from CSV if omitted.
  - match_strictness (string, optional): Matching sensitivity — "loose" (more matches), "normal" (default), or "strict" (fewer false positives).
  - sign_convention (string, optional): How to treat CSV amount signs — "auto" (default, detects from data), "invert" (negate all amounts), "as_is" (use amounts unchanged). Useful when auto-detection fails for liability accounts.
  - dry_run (boolean, optional): Preview actions without executing. Default: true.
  - auto_create_transactions (boolean, optional): Auto-create missing transactions. Default: false.
  - auto_update_cleared_status (boolean, optional): Auto-mark matched transactions as cleared. Default: false.
  - auto_unclear_missing (boolean, optional): Auto-mark statement-missing cleared transactions as uncleared when reconciliation remains unbalanced. Default: false.
  - max_suggestions_in_output (number, optional): Limit unmatched items and suggestions shown in the human report. Default: 20.

Returns: human-readable reconciliation narrative + structured JSON (unmatched_bank, unmatched_ynab, suggestions, execution_summary when actions are performed).

Examples:
  - Preview reconciliation: set dry_run=true (default)
  - Execute: set dry_run=false and explicitly enable the write flags you want, e.g. auto_update_cleared_status=true

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.
- **ynab_get_user** — Get information about the authenticated YNAB user.

Args:
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: user (id)

Errors:
  - "UNAUTHORIZED" → YNAB token expired or invalid
- **ynab_set_default_budget** — Set a default budget so other tools don't require budget_id every call.

Args:
  - budget_id (string, required): Budget UUID to set as default. Validates against YNAB API.

Returns: success, default_budget_id, cache_warm_started.

Examples:
  - Set default: provide the UUID from ynab_list_budgets

Errors:
  - "Budget not found" → invalid budget_id
- **ynab_get_default_budget** — Get the currently configured default budget ID.

Args:
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: default_budget_id (null if not set), has_default.
- **ynab_diagnostic_info** — Get comprehensive diagnostic information about the MCP server (health, cache, delta, security).

Args:
  - include_memory (boolean, optional): Include memory usage. Default: true.
  - include_environment (boolean, optional): Include env info. Default: true.
  - include_server (boolean, optional): Include server info. Default: true.
  - include_security (boolean, optional): Include security stats. Default: true.
  - include_cache (boolean, optional): Include cache metrics. Default: true.
  - include_delta (boolean, optional): Include delta cache info. Default: true.
  - response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: diagnostics object with requested sections.
- **ynab_clear_cache** — Clear all in-memory caches. Safe operation — no YNAB data is modified.

Args: (none)

Returns: success.

Use when: you need fresh data after external YNAB changes, or to free memory.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "ynab-mcpb": {
    "command": "npx",
    "args": ["-y","@dizzlkheinz/ynab-mcpb@latest"],
    "env": {
      "YNAB_ACCESS_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `YNAB_ACCESS_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What ynab-mcpb does

ynab-mcpb exposes YNAB data and operations to MCP-compatible AI assistants. Its tools cover budget selection and summaries, account and category lookup, payees, months, transactions, scheduled transactions, and user information. Read operations can return Markdown tables or structured JSON.

The server also includes workflows beyond basic CRUD operations. Receipt itemization creates a split transaction and distributes tax across line items. Bank reconciliation accepts CSV data, compares it with YNAB transactions using payee and date matching, identifies missing or mismatched entries, and can apply recommended changes. Spending analysis tools compare activity across periods.

## How it works

The process runs locally and communicates with YNAB through the YNAB API. An MCP client sends tool calls generated from plain-language requests, and the server reads or modifies the selected YNAB budget. The server has a 35-tool surface, with startup profiles that control which tools are registered.

Delta sync can be enabled to fetch only data changed since the previous request. Caching behavior can be adjusted with a time-to-live and a maximum entry count. MCP-native features include structured outputs, annotations, completions, and resource templates.

Write operations default to preview mode. A mutation first performs its dry-run path and returns a short-lived, single-use confirmation tied to the validated tool and arguments. Read-only mode omits mutation tools, while enabled mode permits direct writes.

## Setup and configuration

Create a YNAB personal access token in the YNAB web app under Account Settings, Developer Settings, and New Token. Keep the token in the MCP client's secret configuration rather than placing it in conversations or logs.

Claude Desktop users can install the latest MCPB release by downloading the file and dragging it into the application, or configure the npm package with `npx`. Cline in VS Code and Codex can also launch `@dizzlkheinz/ynab-mcpb@latest` with `YNAB_ACCESS_TOKEN` in the environment. Other MCP clients can use the same stdio command:

```text
npx -y @dizzlkheinz/ynab-mcpb@latest
```

Configuration includes `YNAB_EXPORT_PATH` for exported transaction files, `YNAB_MCP_ENABLE_DELTA` for delta sync, `YNAB_MCP_WRITE_MODE` for write safety, and `YNAB_MCP_TOOL_PROFILE` for the `core`, `read-only`, or `full` tool surface. Cache TTL and capacity are controlled with `YNAB_MCP_CACHE_DEFAULT_TTL_MS` and `YNAB_MCP_CACHE_MAX_ENTRIES`.

## Tools and capabilities

The tool groups are:

- Budgets, accounts, categories, payees, months, and user information
- Transaction listing, creation, updates, deletion, export, comparison, and receipt splits
- Scheduled transaction creation, review, updates, and deletion
- CSV reconciliation and spending analysis across periods
- Diagnostics and cache clearing

Transaction amounts can use decimal fields such as `amount_decimal`, or explicit milliunit fields. The corresponding budget category fields support decimal and milliunit forms as well.

## Limitations and notes

YNAB access requires a personal access token, and financial data returned by the tools may be processed by the AI provider selected in the MCP client. The reconciliation workflow is marked beta. The default write mode requires an exact confirmation token that expires after two minutes and can be used only once. The server requires Node.js 24 or newer when installed through its package workflow.

_Full upstream README: https://allmcps.com/mcp/ynab-mcpb/readme_