Category Tools¶

Categories are the heart of YNAB budgeting -- they're where you give every dollar a job. Category tools let you browse your budget structure, check balances and goal progress, create new categories, and set monthly budget amounts. If budgeting in YNAB is about answering "what does this money need to do?", categories are where you write those answers down.

Categories are organized into category groups (like "Monthly Bills", "Fun Money", "Savings Goals") that help you see the big picture. Each group contains individual categories (like "Rent", "Electric", "Internet" under "Monthly Bills").

Usage Examples¶

You: Show me my budget categories.

Claude calls manage_categories with action list and responds:

Monthly Bills: - Rent -- Budgeted: $1,500.00 | Activity: -$1,500.00 | Balance: $0.00 - Electric -- Budgeted: $120.00 | Activity: -$95.40 | Balance: $24.60 - Internet -- Budgeted: $75.00 | Activity: $0.00 | Balance: $75.00

Fun Money: - Dining Out -- Budgeted: $200.00 | Activity: -$142.30 | Balance: $57.70 - Entertainment -- Budgeted: $100.00 | Activity: -$35.99 | Balance: $64.01

You: How's my Groceries category doing?

Claude calls manage_categories with action get and responds:

Category: Groceries Budgeted: $600.00 Activity: -$423.17 Balance: $176.83 Goal: Monthly Funding -- Target: $600.00 (71% complete)

You: Set my Dining Out budget to $250 for this month.

Claude calls manage_categories with action set_month_budget, converting dollars to milliunits:

Updated Dining Out for March 2026: Budgeted: $250.00

You: Create a new category called "Concert Fund" in my Savings Goals group.

Claude calls manage_categories with action create:

Category created: Concert Fund Group: Savings Goals

Available Actions¶

Action	Description
`list`	List all categories grouped by category group
`get`	Get details for a specific category (with goal info)
`create`	Create a new category in a group
`update`	Update a category's name or note
`create_group`	Create a new category group
`update_group`	Rename a category group
`set_month_budget`	Set the budgeted amount for a category in a month

API Reference¶

manage_categories `async` ¶

manage_categories(
    ctx: Context,
    action: Literal[
        "list",
        "get",
        "create",
        "update",
        "create_group",
        "update_group",
        "set_month_budget",
    ],
    budget_id_or_name: str | None = None,
    include_hidden: bool = False,
    category_id: str | None = None,
    category_group_id: str | None = None,
    name: str | None = None,
    note: str | None = None,
    goal_target: float | None = None,
    goal_target_date: str | None = None,
    month: str | None = None,
    budgeted: float | None = None,
) -> str

Manage YNAB categories: list, get, create, update, and budget by month.

Actions

list: List all categories. Uses budget_id_or_name, include_hidden. get: Get category details. Uses category_id (required). create: Create category. Uses name (required), category_group_id, note, goal_target, goal_target_date. update: Update category. Uses category_id (required), name, note, goal_target, goal_target_date. create_group: Create category group. Uses name (required). update_group: Update category group. Uses category_group_id (required), name (required). set_month_budget: Get or set month budget. Uses category_id (required), month, budgeted (omit to get current value).

Parameters:

ctx (Context) –

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

The operation to perform.
budget_id_or_name (str | None, default: None ) –

Budget UUID or name. Auto-resolves if only one budget exists.
include_hidden (bool, default: False ) –

If True, include hidden categories (list only).
category_id (str | None, default: None ) –

The category UUID (get, update, set_month_budget).
category_group_id (str | None, default: None ) –

Category group UUID (create, update_group).
name (str | None, default: None ) –

Name for category or group.
note (str | None, default: None ) –

Category note (create, update).
goal_target (float | None, default: None ) –

Goal target in dollars (create, update).
goal_target_date (str | None, default: None ) –

Goal target date (create, update).
month (str | None, default: None ) –

Month as YYYY-MM or YYYY-MM-DD (set_month_budget).
budgeted (float | None, default: None ) –

Budgeted amount in dollars (set_month_budget).

Returns:

str –

Structured text with category information or confirmation.

Raises:

ToolError –

If required parameters for the action are missing.

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

@mcp.tool
async def manage_categories(  # noqa: PLR0913, PLR0917, C901, PLR0911
    ctx: Context,
    action: Literal[
        "list",
        "get",
        "create",
        "update",
        "create_group",
        "update_group",
        "set_month_budget",
    ],
    budget_id_or_name: str | None = None,
    include_hidden: bool = False,  # noqa: FBT001, FBT002
    category_id: str | None = None,
    category_group_id: str | None = None,
    name: str | None = None,
    note: str | None = None,
    goal_target: float | None = None,
    goal_target_date: str | None = None,
    month: str | None = None,
    budgeted: float | None = None,
) -> str:
    """Manage YNAB categories: list, get, create, update, and budget by month.

    Actions:
        list: List all categories. Uses budget_id_or_name, include_hidden.
        get: Get category details. Uses category_id (required).
        create: Create category. Uses name (required), category_group_id, note,
            goal_target, goal_target_date.
        update: Update category. Uses category_id (required), name, note,
            goal_target, goal_target_date.
        create_group: Create category group. Uses name (required).
        update_group: Update category group. Uses category_group_id (required),
            name (required).
        set_month_budget: Get or set month budget. Uses category_id (required),
            month, budgeted (omit to get current value).

    Args:
        ctx: The MCP context providing access to lifespan dependencies.
        action: The operation to perform.
        budget_id_or_name: Budget UUID or name. Auto-resolves if only
            one budget exists.
        include_hidden: If True, include hidden categories (list only).
        category_id: The category UUID (get, update, set_month_budget).
        category_group_id: Category group UUID (create, update_group).
        name: Name for category or group.
        note: Category note (create, update).
        goal_target: Goal target in dollars (create, update).
        goal_target_date: Goal target date (create, update).
        month: Month as YYYY-MM or YYYY-MM-DD (set_month_budget).
        budgeted: Budgeted amount in dollars (set_month_budget).

    Returns:
        Structured text with category information or confirmation.

    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_categories(
            app, budget_id, info, include_hidden=include_hidden
        )
    if action == "get":
        if category_id is None:
            msg = "category_id is required for action='get'"
            raise ToolError(msg)
        return await _get_category(app, budget_id, info, category_id=category_id)
    if action == "create":
        if name is None:
            msg = "name is required for action='create'"
            raise ToolError(msg)
        return await _create_category(
            app,
            budget_id,
            name=name,
            category_group_id=category_group_id,
            note=note,
            goal_target=goal_target,
            goal_target_date=goal_target_date,
        )
    if action == "update":
        if category_id is None:
            msg = "category_id is required for action='update'"
            raise ToolError(msg)
        return await _update_category(
            app,
            budget_id,
            category_id=category_id,
            name=name,
            note=note,
            goal_target=goal_target,
            goal_target_date=goal_target_date,
        )
    if action == "create_group":
        if name is None:
            msg = "name is required for action='create_group'"
            raise ToolError(msg)
        return await _create_group(app, budget_id, name=name)
    if action == "update_group":
        if category_group_id is None or name is None:
            msg = "category_group_id and name are required for action='update_group'"
            raise ToolError(msg)
        return await _update_group(
            app, budget_id, category_group_id=category_group_id, name=name
        )
    if category_id is None:
        msg = "category_id is required for action='set_month_budget'"
        raise ToolError(msg)
    return await _set_month_budget(
        app, budget_id, category_id=category_id, month=month, budgeted=budgeted
    )

Category Tools¶

Usage Examples¶

Available Actions¶

API Reference¶

manage_categories async ¶

manage_categories `async` ¶