Transaction Tools¶

Transactions are the individual money movements that make up your budget's story. Transaction tools give you full control -- creating new transactions, searching and filtering existing ones, updating details, deleting mistakes, and even batch operations for importing or bulk updates. This is the most powerful tool in the set, and the one you'll likely use most often.

Every transaction in YNAB has a cleared state that tracks its journey:

Uncleared [U] -- Entered but not yet confirmed by the bank
Cleared [C] -- Confirmed to match your bank statement
Reconciled [R] -- Locked in after reconciliation (no further edits)

Usage Examples¶

You: Show me my recent transactions.

Claude calls manage_transactions with action list and responds:

10 most recent transactions: - 2026-03-05 | Whole Foods | -$87.32 | Groceries [C] - 2026-03-04 | Shell Gas | -$42.00 | Transportation [U] - 2026-03-03 | Spotify | -$15.99 | Subscriptions [C] - 2026-03-01 | Employer Inc | $3,200.00 | Income [R]

You: I spent $45 at Target on household supplies today.

Claude calls manage_transactions with action create:

Transaction created: - 2026-03-06 | Target | -$45.00 | Household Supplies [U]

You: Show me all dining transactions from last month.

Claude calls manage_transactions with action list with category and date filters:

8 transactions in Dining Out (February 2026): - 2026-02-28 | Thai Palace | -$38.50 | Dining Out [C] - 2026-02-22 | Chipotle | -$12.75 | Dining Out [C] ... Total: -$342.17

You: Update that Shell Gas transaction -- it should be $44.50, not $42.

Claude calls manage_transactions with action update:

Transaction updated: - 2026-03-04 | Shell Gas | -$44.50 | Transportation [U]

Available Actions¶

Action	Description
`list`	List transactions with optional date/category filters
`get`	Get full details for a specific transaction
`create`	Create a new transaction
`update`	Update an existing transaction's details
`delete`	Delete a transaction
`batch_create`	Create multiple transactions at once
`batch_update`	Update multiple transactions at once
`import`	Import transactions (matches against existing by amount/date)

API Reference¶

manage_transactions `async` ¶

manage_transactions(
    ctx: Context,
    action: Literal[
        "list",
        "get",
        "create",
        "update",
        "delete",
        "batch_create",
        "batch_update",
        "import",
    ],
    budget_id_or_name: str = "last-used",
    transaction_id: str | None = None,
    account_id: str | None = None,
    date: str | None = None,
    amount: float | None = None,
    payee_name: str | None = None,
    payee_id: str | None = None,
    category_id: str | None = None,
    memo: str | None = None,
    cleared: str | None = None,
    approved: bool | None = None,
    flag_color: str | None = None,
    since_date: str | None = None,
    until_date: str | None = None,
    type: str | None = None,
    month: str | None = None,
    limit: int | None = None,
    transactions: list[dict[str, Any]] | None = None,
) -> str

Manage YNAB transactions: list, get, create, update, delete, batch, import.

Dispatches to the appropriate action based on the action parameter.

Actions

list: List transactions with optional filtering. Params: budget_id_or_name, since_date, until_date, type, account_id, category_id, payee_id, month, limit. Only one of account_id/category_id/payee_id/month at a time. get: Get full detail for a transaction. Params: budget_id_or_name, transaction_id (required). create: Create a new transaction. Params: budget_id_or_name, account_id (required), date (required), amount (required), payee_name, payee_id, category_id, memo, cleared, approved, flag_color. update: Update an existing transaction. Params: budget_id_or_name, transaction_id (required), plus any optional fields to change. delete: Delete a transaction. Params: budget_id_or_name, transaction_id (required). batch_create: Create multiple transactions at once. Params: budget_id_or_name, transactions (required, list[dict]). batch_update: Update multiple transactions at once. Params: budget_id_or_name, transactions (required, list[dict]). import: Import transactions from linked bank accounts. Params: budget_id_or_name only.

Parameters:

ctx (Context) –

The MCP context providing access to lifespan dependencies.
action (Literal['list', 'get', 'create', 'update', 'delete', 'batch_create', 'batch_update', 'import']) –

The operation to perform.
budget_id_or_name (str, default: 'last-used' ) –

Budget UUID or name. Defaults to "last-used".
transaction_id (str | None, default: None ) –

Transaction UUID (required for get, update, delete).
account_id (str | None, default: None ) –

Account UUID (required for create, filter for list).
date (str | None, default: None ) –

Transaction date as ISO string (required for create).
amount (float | None, default: None ) –

Amount in dollars (required for create, converted to milliunits).
payee_name (str | None, default: None ) –

Payee display name.
payee_id (str | None, default: None ) –

Payee UUID (filter for list, field for create/update).
category_id (str | None, default: None ) –

Category UUID (filter for list, field for create/update).
memo (str | None, default: None ) –

Transaction memo.
cleared (str | None, default: None ) –

Cleared status ("cleared", "uncleared", "reconciled").
approved (bool | None, default: None ) –

Whether the transaction is approved.
flag_color (str | None, default: None ) –

Flag color for the transaction.
since_date (str | None, default: None ) –

Only return transactions on or after this date (list only).
until_date (str | None, default: None ) –

Only return transactions on or before this date (list only).
type (str | None, default: None ) –

Filter by type ("uncategorized" or "unapproved", list only).
month (str | None, default: None ) –

Filter by month (list only, "YYYY-MM" or "YYYY-MM-DD").
limit (int | None, default: None ) –

Maximum number of transactions to return (list only).
transactions (list[dict[str, Any]] | None, default: None ) –

List of transaction dicts (batch_create/batch_update only).

Returns:

str –

Structured text with the requested transaction data.

Raises:

ToolError –

If required parameters for the action are missing.

Source code in src/ynaa_mcp/tools/transactions.py

@mcp.tool
async def manage_transactions(  # noqa: PLR0913, PLR0917, C901, PLR0911
    ctx: Context,
    action: Literal[
        "list",
        "get",
        "create",
        "update",
        "delete",
        "batch_create",
        "batch_update",
        "import",
    ],
    budget_id_or_name: str = "last-used",
    transaction_id: str | None = None,
    account_id: str | None = None,
    date: str | None = None,
    amount: float | None = None,
    payee_name: str | None = None,
    payee_id: str | None = None,
    category_id: str | None = None,
    memo: str | None = None,
    cleared: str | None = None,
    approved: bool | None = None,  # noqa: FBT001
    flag_color: str | None = None,
    since_date: str | None = None,
    until_date: str | None = None,
    type: str | None = None,  # noqa: A002
    month: str | None = None,
    limit: int | None = None,
    transactions: list[dict[str, Any]] | None = None,
) -> str:
    """Manage YNAB transactions: list, get, create, update, delete, batch, import.

    Dispatches to the appropriate action based on the ``action`` parameter.

    Actions:
        list: List transactions with optional filtering.
            Params: budget_id_or_name, since_date, until_date, type,
            account_id, category_id, payee_id, month, limit.
            Only one of account_id/category_id/payee_id/month at a time.
        get: Get full detail for a transaction.
            Params: budget_id_or_name, transaction_id (required).
        create: Create a new transaction.
            Params: budget_id_or_name, account_id (required), date (required),
            amount (required), payee_name, payee_id, category_id, memo,
            cleared, approved, flag_color.
        update: Update an existing transaction.
            Params: budget_id_or_name, transaction_id (required),
            plus any optional fields to change.
        delete: Delete a transaction.
            Params: budget_id_or_name, transaction_id (required).
        batch_create: Create multiple transactions at once.
            Params: budget_id_or_name, transactions (required, list[dict]).
        batch_update: Update multiple transactions at once.
            Params: budget_id_or_name, transactions (required, list[dict]).
        import: Import transactions from linked bank accounts.
            Params: budget_id_or_name only.

    Args:
        ctx: The MCP context providing access to lifespan dependencies.
        action: The operation to perform.
        budget_id_or_name: Budget UUID or name. Defaults to "last-used".
        transaction_id: Transaction UUID (required for get, update, delete).
        account_id: Account UUID (required for create, filter for list).
        date: Transaction date as ISO string (required for create).
        amount: Amount in dollars (required for create, converted to milliunits).
        payee_name: Payee display name.
        payee_id: Payee UUID (filter for list, field for create/update).
        category_id: Category UUID (filter for list, field for create/update).
        memo: Transaction memo.
        cleared: Cleared status ("cleared", "uncleared", "reconciled").
        approved: Whether the transaction is approved.
        flag_color: Flag color for the transaction.
        since_date: Only return transactions on or after this date (list only).
        until_date: Only return transactions on or before this date (list only).
        type: Filter by type ("uncategorized" or "unapproved", list only).
        month: Filter by month (list only, "YYYY-MM" or "YYYY-MM-DD").
        limit: Maximum number of transactions to return (list only).
        transactions: List of transaction dicts (batch_create/batch_update only).

    Returns:
        Structured text with the requested transaction data.

    Raises:
        ToolError: If required parameters for the action are missing.
    """
    app = cast("AppContext", ctx.lifespan_context)
    budget_id, _info = await resolve_budget(
        app.client, budget_id_or_name, cache=app.cache
    )

    if action == "list":
        return await _list_transactions(
            app,
            budget_id,
            since_date,
            until_date,
            type,
            account_id,
            category_id,
            payee_id,
            month,
            limit,
        )

    if action == "get":
        if transaction_id is None:
            msg = "action='get' requires 'transaction_id'"
            raise ToolError(msg)
        return await _get_transaction(app, budget_id, transaction_id)

    if action == "create":
        return await _create_transaction(
            app,
            budget_id,
            account_id,
            date,
            amount,
            payee_name,
            payee_id,
            category_id,
            memo,
            cleared,
            approved,
            flag_color,
        )

    if action == "update":
        if transaction_id is None:
            msg = "action='update' requires 'transaction_id'"
            raise ToolError(msg)
        return await _update_transaction(
            app,
            budget_id,
            transaction_id,
            account_id,
            date,
            amount,
            payee_name,
            payee_id,
            category_id,
            memo,
            cleared,
            approved,
            flag_color,
        )

    if action == "delete":
        if transaction_id is None:
            msg = "action='delete' requires 'transaction_id'"
            raise ToolError(msg)
        return await _delete_transaction(app, budget_id, transaction_id)

    if action == "batch_create":
        return await _batch_create_transactions(app, budget_id, transactions)

    if action == "batch_update":
        return await _batch_update_transactions(app, budget_id, transactions)

    # Last action: import
    return await _import_transactions(app, budget_id)

Transaction Tools¶

Usage Examples¶

Available Actions¶

API Reference¶

manage_transactions async ¶

manage_transactions `async` ¶