YNAB Receipts & Reconciliation

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.

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.

Deterministically compare two complete spending periods and calculate total and per-group differences.

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.

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.

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.

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.

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: created transaction with account_balance.

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.

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.

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.

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: deleted transaction id and updated account balance.

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.

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.

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

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

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

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

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.

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

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

Get one scheduled transaction by ID.

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

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

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

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

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

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

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

List scheduled transactions with delta caching and pagination. Amounts are returned in decimal currency and explicit milliunits.

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

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.

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

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.

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.

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.
• dry_run (boolean, optional): Preview without saving.

Returns: updated transaction with updated_balance.

Write safety: call without confirmation_token to preview. Execute the identical validated request with the short-lived confirmation_token returned by that preview.

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.
• 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.