update_category_budget

Modify the budgeted amount for a YNAB category in a specific month to adjust your financial planning and maintain accurate budget tracking.

Instructions

Update the budgeted amount for a category in a specific month.

Args:
    budget_id: The ID of the budget (use 'last-used' for default budget)
    month: Month in YYYY-MM-DD format (e.g., 2025-01-01 for January 2025)
    category_id: The category ID to update
    budgeted: The budgeted amount to set

Returns:
    JSON string with the updated category

Input Schema

TableJSON Schema

Name	Required	Description	Default
`budget_id`	Yes
`budgeted`	Yes
`category_id`	Yes
`month`	Yes

Implementation Reference

src/ynab_mcp/server.py:432-452 (handler)

MCP tool handler function decorated with @mcp.tool(), which registers the tool and executes by calling the YNABClient method.

@mcp.tool()
async def update_category_budget(
    budget_id: str,
    month: str,
    category_id: str,
    budgeted: float,
) -> str:
    """Update the budgeted amount for a category in a specific month.

    Args:
        budget_id: The ID of the budget (use 'last-used' for default budget)
        month: Month in YYYY-MM-DD format (e.g., 2025-01-01 for January 2025)
        category_id: The category ID to update
        budgeted: The budgeted amount to set

    Returns:
        JSON string with the updated category
    """
    client = get_ynab_client()
    result = await client.update_category_budget(budget_id, month, category_id, budgeted)
    return json.dumps(result, indent=2)

src/ynab_mcp/ynab_client.py:1252-1291 (helper)

Core helper method in YNABClient class that performs the actual YNAB API PATCH request to update the category's budgeted amount for the specified month.

async def update_category_budget(
    self,
    budget_id: str,
    month: str,
    category_id: str,
    budgeted: float,
) -> dict[str, Any]:
    """Update the budgeted amount for a category in a specific month.

    Uses direct API calls since ynab-sdk is read-only.

    Args:
        budget_id: The budget ID or 'last-used'
        month: Month in YYYY-MM-DD format (e.g., 2025-01-01)
        category_id: The category ID to update
        budgeted: The budgeted amount to set

    Returns:
        Updated category dictionary
    """
    try:
        url = f"{self.api_base_url}/budgets/{budget_id}/months/{month}/categories/{category_id}"
        data = {
            "category": {
                "budgeted": int(budgeted * 1000)  # Convert to milliunits
            }
        }

        result = await self._make_request_with_retry("patch", url, json=data)

        cat = result["data"]["category"]
        return {
            "id": cat["id"],
            "name": cat["name"],
            "budgeted": cat["budgeted"] / 1000 if cat["budgeted"] else 0,
            "activity": cat["activity"] / 1000 if cat["activity"] else 0,
            "balance": cat["balance"] / 1000 if cat["balance"] else 0,
        }
    except Exception as e:
        raise Exception(f"Failed to update category budget: {e}") from e

src/ynab_mcp/server.py:432-452 (registration)

The @mcp.tool() decorator registers this function as an MCP tool.

@mcp.tool()
async def update_category_budget(
    budget_id: str,
    month: str,
    category_id: str,
    budgeted: float,
) -> str:
    """Update the budgeted amount for a category in a specific month.

    Args:
        budget_id: The ID of the budget (use 'last-used' for default budget)
        month: Month in YYYY-MM-DD format (e.g., 2025-01-01 for January 2025)
        category_id: The category ID to update
        budgeted: The budgeted amount to set

    Returns:
        JSON string with the updated category
    """
    client = get_ynab_client()
    result = await client.update_category_budget(budget_id, month, category_id, budgeted)
    return json.dumps(result, indent=2)

YNAB MCP Server