get_categories
Retrieve all budget categories and groups from your YNAB budget to manage spending targets and track financial allocations.
Instructions
Get all categories for a budget.
Args:
budget_id: The ID of the budget (use 'last-used' for default budget)
include_hidden: Include hidden categories and groups (default: False)
Returns:
JSON string with category groups and categoriesInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | Yes | ||
| include_hidden | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/ynab_mcp/server.py:83-96 (handler)MCP tool handler and registration for get_categories. Decorated with @mcp.tool(), delegates to YNABClient.get_categories(budget_id, include_hidden), formats result as indented JSON string.
@mcp.tool() async def get_categories(budget_id: str, include_hidden: bool = False) -> str: """Get all categories for a budget. Args: budget_id: The ID of the budget (use 'last-used' for default budget) include_hidden: Include hidden categories and groups (default: False) Returns: JSON string with category groups and categories """ client = get_ynab_client() result = await client.get_categories(budget_id, include_hidden) return json.dumps(result, indent=2) - src/ynab_mcp/ynab_client.py:301-349 (helper)Core helper method in YNABClient that implements the get_categories logic: calls YNAB SDK, filters out hidden/deleted categories and groups unless include_hidden=True, structures response as list of category groups with categories.
async def get_categories( self, budget_id: str, include_hidden: bool = False ) -> list[dict[str, Any]]: """Get all categories for a budget. Args: budget_id: The budget ID or 'last-used' include_hidden: Include hidden categories and groups (default: False) Returns: List of category dictionaries grouped by category groups """ try: response = self.client.categories.get_categories(budget_id) category_groups = [] for group in response.data.category_groups: categories = [] for category in group.categories: # Skip hidden and deleted categories unless requested if not include_hidden and (category.hidden or category.deleted): continue categories.append( { "id": category.id, "name": category.name, "balance": category.balance / 1000 if category.balance else 0, "hidden": category.hidden, } ) # Skip hidden groups unless requested, and skip empty groups if (not include_hidden and group.hidden) or not categories: continue category_groups.append( { "id": group.id, "name": group.name, "hidden": group.hidden, "categories": categories, } ) return category_groups except Exception as e: raise Exception(f"Failed to get categories: {e}") from e