Scheduled Transaction Tools¶

Scheduled transactions represent your recurring and upcoming financial commitments -- rent, subscriptions, loan payments, regular transfers. These tools let you view, create, update, and manage scheduled transactions so you always know what's coming up and can plan ahead.

In YNAB, scheduled transactions automatically create real transactions on their due dates. Setting them up means you'll never forget a bill and your budget always reflects upcoming obligations.

Usage Examples¶

You: What recurring transactions do I have?

Claude calls manage_scheduled_transactions with action list and responds:

6 scheduled transactions found: - 2026-04-01 | Landlord | -$1,500.00 | Rent [monthly] - 2026-03-15 | Netflix | -$22.99 | Subscriptions [monthly] - 2026-03-20 | Electric Company | -$120.00 | Utilities [monthly] - 2026-04-01 | Gym | -$49.99 | Health [monthly] - 2026-03-14 | Employer Inc | $3,200.00 | Income [everyOtherWeek] - 2026-06-15 | Insurance Co | -$600.00 | Insurance [twiceAYear]

You: Tell me more about my rent payment.

Claude calls manage_scheduled_transactions with action get and responds:

Scheduled Transaction: Landlord Amount: -$1,500.00 Frequency: monthly Next date: 2026-04-01 Account: Checking Category: Rent Memo: April rent

You: Schedule a new monthly payment of $50 to my gym starting April 1st.

Claude calls manage_scheduled_transactions with action create:

Scheduled transaction created: - Gym Membership | -$50.00 | monthly starting 2026-04-01

You: Cancel my Netflix subscription in YNAB.

Claude calls manage_scheduled_transactions with action delete:

Scheduled transaction deleted: Netflix ($22.99/month)

Available Actions¶

Action	Description
`list`	List all scheduled transactions
`get`	Get details for a specific scheduled transaction
`create`	Create a new scheduled/recurring transaction
`update`	Update an existing scheduled transaction
`delete`	Delete a scheduled transaction

API Reference¶

manage_scheduled_transactions `async` ¶

manage_scheduled_transactions(
    ctx: Context,
    action: Literal["list", "get", "create", "update", "delete"],
    budget_id_or_name: str = "last-used",
    scheduled_transaction_id: str | None = None,
    account_id: str | None = None,
    date: str | None = None,
    amount: float | None = None,
    frequency: str | None = None,
    payee_name: str | None = None,
    payee_id: str | None = None,
    category_id: str | None = None,
    memo: str | None = None,
    flag_color: str | None = None,
) -> str

Manage YNAB scheduled transactions: list, get, create, update, delete.

Dispatches to the appropriate action based on the action parameter.

Actions

list: List all scheduled transactions (excludes deleted). Params: budget_id_or_name. get: Get full detail for a scheduled transaction. Params: budget_id_or_name, scheduled_transaction_id (required). create: Create a new scheduled transaction. Params: budget_id_or_name, account_id (required), date (required), amount, frequency, payee_name, payee_id, category_id, memo, flag_color. update: Update an existing scheduled transaction. Params: budget_id_or_name, scheduled_transaction_id (required), plus any optional fields to change. delete: Delete a scheduled transaction. Params: budget_id_or_name, scheduled_transaction_id (required).

Parameters:

ctx (Context) –

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

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

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

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

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

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

Amount in dollars (converted to YNAB milliunits).
frequency (str | None, default: None ) –

Recurrence frequency (never, daily, weekly, everyOtherWeek, twiceAMonth, every4Weeks, monthly, everyOtherMonth, every3Months, every4Months, twiceAYear, yearly, everyOtherYear).
payee_name (str | None, default: None ) –

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

Payee UUID.
category_id (str | None, default: None ) –

Category UUID.
memo (str | None, default: None ) –

Scheduled transaction memo.
flag_color (str | None, default: None ) –

Flag color for the scheduled transaction.

Returns:

str –

Structured text with the requested scheduled transaction data.

Raises:

ToolError –

If required parameters for the action are missing.

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

@mcp.tool
async def manage_scheduled_transactions(  # noqa: PLR0913, PLR0917
    ctx: Context,
    action: Literal["list", "get", "create", "update", "delete"],
    budget_id_or_name: str = "last-used",
    scheduled_transaction_id: str | None = None,
    account_id: str | None = None,
    date: str | None = None,
    amount: float | None = None,
    frequency: str | None = None,
    payee_name: str | None = None,
    payee_id: str | None = None,
    category_id: str | None = None,
    memo: str | None = None,
    flag_color: str | None = None,
) -> str:
    """Manage YNAB scheduled transactions: list, get, create, update, delete.

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

    Actions:
        list: List all scheduled transactions (excludes deleted).
            Params: budget_id_or_name.
        get: Get full detail for a scheduled transaction.
            Params: budget_id_or_name, scheduled_transaction_id (required).
        create: Create a new scheduled transaction.
            Params: budget_id_or_name, account_id (required), date (required),
            amount, frequency, payee_name, payee_id, category_id, memo,
            flag_color.
        update: Update an existing scheduled transaction.
            Params: budget_id_or_name, scheduled_transaction_id (required),
            plus any optional fields to change.
        delete: Delete a scheduled transaction.
            Params: budget_id_or_name, scheduled_transaction_id (required).

    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".
        scheduled_transaction_id: Scheduled transaction UUID (required for
            get, update, delete).
        account_id: Account UUID (required for create).
        date: Scheduled transaction date as ISO string (required for create).
        amount: Amount in dollars (converted to YNAB milliunits).
        frequency: Recurrence frequency (never, daily, weekly, everyOtherWeek,
            twiceAMonth, every4Weeks, monthly, everyOtherMonth,
            every3Months, every4Months, twiceAYear, yearly,
            everyOtherYear).
        payee_name: Payee display name.
        payee_id: Payee UUID.
        category_id: Category UUID.
        memo: Scheduled transaction memo.
        flag_color: Flag color for the scheduled transaction.

    Returns:
        Structured text with the requested scheduled 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_scheduled(app, budget_id)

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

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

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

    # Last action: delete
    if scheduled_transaction_id is None:
        msg = "action='delete' requires 'scheduled_transaction_id'"
        raise ToolError(msg)
    return await _delete_scheduled(app, budget_id, scheduled_transaction_id)

Scheduled Transaction Tools¶

Usage Examples¶

Available Actions¶

API Reference¶

manage_scheduled_transactions async ¶

manage_scheduled_transactions `async` ¶