Month Tools¶

YNAB is built around monthly budgeting -- each month is a fresh start where you assign your available dollars to categories. Month tools give you the monthly view: income, budgeted amounts, spending activity, and the all-important "To Be Budgeted" number. You can also dig into money movement patterns to understand where your dollars are flowing.

The Age of Money metric is especially useful here -- it tells you how many days old the money you're spending today is. A higher age means you're spending older money, which is a sign of financial stability.

Usage Examples¶

You: How did last month go?

Claude calls manage_months with action get for February 2026:

February 2026: Income: $5,400.00 Budgeted: $5,200.00 Activity: -$4,870.00 To be budgeted: $200.00 Age of money: 38 days

You: Show me all my budget months.

Claude calls manage_months with action list and responds:

24 months found: - 2026-03-01 -- Income: $3,200.00 | Budgeted: $3,200.00 | TBB: $0.00 - 2026-02-01 -- Income: $5,400.00 | Budgeted: $5,200.00 | TBB: $200.00 - 2026-01-01 -- Income: $5,400.00 | Budgeted: $5,400.00 | TBB: $0.00 ...

You: Show me the money movements for this month.

Claude calls manage_months with action list_money_movements:

Money movements for March 2026: - Groceries: -$423.17 - Rent: -$1,500.00 - Dining Out: -$142.30 ...

You: Break that down by category group.

Claude calls manage_months with action list_money_movement_groups:

Money movements by group for March 2026: Monthly Bills: -$1,695.40 Everyday Expenses: -$743.22 Fun Money: -$178.29 Savings Goals: -$500.00

Available Actions¶

Action	Description
`list`	List all budget months with summaries
`get`	Get detailed info for a specific month
`list_money_movements`	See category-level money movements for a month
`list_money_movement_groups`	See group-level money movements for a month

API Reference¶

manage_months `async` ¶

manage_months(
    ctx: Context,
    action: Literal[
        "list", "get", "list_money_movements", "list_money_movement_groups"
    ],
    budget_id_or_name: str = "last-used",
    month: str | None = None,
) -> str

Manage YNAB budget months: list, get detail, and view money movements.

Dispatches to the appropriate action based on the action parameter.

Actions

list: List all budget months with income, budgeted, activity, to-be-budgeted, and age of money. Params: budget_id_or_name. get: Get detailed month with category breakdowns grouped by category group. Params: budget_id_or_name, month (required). list_money_movements: List money movements (category-level). Params: budget_id_or_name, month (optional -- all if omitted). list_money_movement_groups: List money movement groups (group-level). Params: budget_id_or_name, month (optional -- all if omitted).

Parameters:

ctx (Context) –

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

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

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

Month as "YYYY-MM" or "YYYY-MM-DD". Required for "get", optional for "list_money_movements" and "list_money_movement_groups".

Returns:

str –

Structured text with the requested month data.

Raises:

ToolError –

If "get" is called without month.

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

@mcp.tool
async def manage_months(
    ctx: Context,
    action: Literal[
        "list", "get", "list_money_movements", "list_money_movement_groups"
    ],
    budget_id_or_name: str = "last-used",
    month: str | None = None,
) -> str:
    """Manage YNAB budget months: list, get detail, and view money movements.

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

    Actions:
        list: List all budget months with income, budgeted, activity,
            to-be-budgeted, and age of money. Params: budget_id_or_name.
        get: Get detailed month with category breakdowns grouped by
            category group. Params: budget_id_or_name, month (required).
        list_money_movements: List money movements (category-level).
            Params: budget_id_or_name, month (optional -- all if omitted).
        list_money_movement_groups: List money movement groups (group-level).
            Params: budget_id_or_name, month (optional -- all if omitted).

    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".
        month: Month as "YYYY-MM" or "YYYY-MM-DD". Required for "get",
            optional for "list_money_movements" and
            "list_money_movement_groups".

    Returns:
        Structured text with the requested month data.

    Raises:
        ToolError: If "get" is called without ``month``.
    """
    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_months(app, budget_id)

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

    if action == "list_money_movements":
        return await _list_money_movements(app, budget_id, month)

    # Last action: list_money_movement_groups
    return await _list_money_movement_groups(app, budget_id, month)

Month Tools¶

Usage Examples¶

Available Actions¶

API Reference¶

manage_months async ¶

manage_months `async` ¶