get_category
Retrieve detailed category information from YNAB including goals, budgeted amounts, activity, and balance for specific budget categories to analyze spending patterns and track financial progress.
Instructions
Get a single category with full details including goal information.
Args:
budget_id: The ID of the budget (use 'last-used' for default budget)
category_id: The category ID
Returns:
JSON string with category details including goals, budgeted amounts, activity, and balance
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | Yes | ||
| category_id | Yes |
Implementation Reference
- src/ynab_mcp/server.py:67-81 (handler)MCP tool handler for get_category. Decorated with @mcp.tool() for automatic registration and schema derivation from signature/docstring. Delegates to YNABClient.get_category and returns JSON.@mcp.tool() async def get_category(budget_id: str, category_id: str) -> str: """Get a single category with full details including goal information. Args: budget_id: The ID of the budget (use 'last-used' for default budget) category_id: The category ID Returns: JSON string with category details including goals, budgeted amounts, activity, and balance """ client = get_ynab_client() result = await client.get_category(budget_id, category_id) return json.dumps(result, indent=2)
- src/ynab_mcp/ynab_client.py:250-300 (helper)Core implementation in YNABClient that fetches single category via YNAB API GET /budgets/{budget_id}/categories/{category_id}, processes response with goal details, converts milliunits, and returns structured dict.async def get_category(self, budget_id: str, category_id: str) -> dict[str, Any]: """Get a single category with all details including goal information. Args: budget_id: The budget ID or 'last-used' category_id: The category ID Returns: Category dictionary with full details Raises: YNABValidationError: If parameters are invalid YNABAPIError: If API request fails """ logger.debug(f"Getting category {category_id} for budget {budget_id}") # Validate inputs budget_id = validate_budget_id(budget_id) url = f"{self.api_base_url}/budgets/{budget_id}/categories/{category_id}" result = await self._make_request_with_retry("get", url) cat = result["data"]["category"] return { "id": cat["id"], "name": cat["name"], "category_group_id": cat.get("category_group_id"), "hidden": cat.get("hidden"), "note": cat.get("note"), "budgeted": cat.get("budgeted", 0) / MILLIUNITS_FACTOR if cat.get("budgeted") else 0, "activity": cat.get("activity", 0) / MILLIUNITS_FACTOR if cat.get("activity") else 0, "balance": cat.get("balance", 0) / MILLIUNITS_FACTOR if cat.get("balance") else 0, "goal_type": cat.get("goal_type"), "goal_target": cat.get("goal_target", 0) / MILLIUNITS_FACTOR if cat.get("goal_target") else 0, "goal_target_month": cat.get("goal_target_month"), "goal_percentage_complete": cat.get("goal_percentage_complete"), "goal_months_to_budget": cat.get("goal_months_to_budget"), "goal_under_funded": cat.get("goal_under_funded", 0) / MILLIUNITS_FACTOR if cat.get("goal_under_funded") else 0, "goal_overall_funded": cat.get("goal_overall_funded", 0) / MILLIUNITS_FACTOR if cat.get("goal_overall_funded") else 0, "goal_overall_left": cat.get("goal_overall_left", 0) / MILLIUNITS_FACTOR if cat.get("goal_overall_left") else 0, }
- src/ynab_mcp/server.py:67-67 (registration)The @mcp.tool() decorator registers the get_category function as an MCP tool.@mcp.tool()
- src/ynab_mcp/server.py:69-77 (schema)Tool schema derived from function signature (budget_id: str, category_id: str -> str) and docstring describing parameters and return value."""Get a single category with full details including goal information. Args: budget_id: The ID of the budget (use 'last-used' for default budget) category_id: The category ID Returns: JSON string with category details including goals, budgeted amounts, activity, and balance """