list-categories
Retrieve all categories, groups, and budgeting details for a specific budget to review available funds and allocated amounts before adjusting budgets.
Instructions
List all categories, groups, and their budgeting details for a given budget. Call this before managing budgeted amounts to see what's available and what's already been allocated.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| budget_id | No | The ID of the budget. If not provided, the default budget will be used. |
Implementation Reference
- src/ynab_mcp_server/server.py:259-289 (handler)The main handler function for the 'list-categories' tool within the handle_call_tool method. It validates input, fetches category groups using ynab_client, and formats a detailed text response with category budgets, spending, balances, and goals.elif name == "list-categories": args = ListCategoriesInput.model_validate(arguments or {}) budget_id = await _get_budget_id(args.model_dump()) category_groups = await ynab_client.get_categories(budget_id=budget_id) if not category_groups: return [types.TextContent(type="text", text="No categories found for this budget.")] output = "Here are the available categories and their status for the current month:\n" for group in category_groups: if not group.hidden and group.categories: output += f"\n--- {group.name} ---\n" for cat in group.categories: if not cat.hidden: details = ( f"Budgeted: {cat.budgeted / 1000:.2f}, " f"Spent: {abs(cat.activity) / 1000:.2f}, " f"Balance: {cat.balance / 1000:.2f}" ) output += f"- {cat.name} (ID: {cat.id})\n - {details}\n" if cat.goal_type: goal_progress = f"{cat.goal_percentage_complete or 0}%" goal_target = ( f"{cat.goal_target / 1000:.2f}" if cat.goal_target else "N/A" ) output += ( f" - Goal ({cat.goal_type}): Target {goal_target}, " f"{goal_progress} complete\n" ) return [types.TextContent(type="text", text=output)]
- Pydantic model defining the input schema for the 'list-categories' tool, inheriting from BudgetIdInput which provides an optional budget_id field.class ListCategoriesInput(BudgetIdInput): pass
- src/ynab_mcp_server/server.py:64-71 (registration)Tool registration in the list_tools handler, defining name, description, and input schema for 'list-categories'.types.Tool( name="list-categories", description=( "List all categories, groups, and their budgeting details for a given budget. " "Call this before managing budgeted amounts to see what's available and what's already been allocated." ), inputSchema=ListCategoriesInput.model_json_schema(), ),
- Helper method in YNABClient that fetches category groups from the YNAB API, used by the list-categories handler.self, budget_id: str ) -> list[ynab.CategoryGroupWithCategories]: response = await self._run_sync(self._categories_api.get_categories, budget_id) return response.data.category_groups
- src/ynab_mcp_server/server.py:30-40 (registration)Includes 'list-categories' in the set of read-only tools, restricting write operations in read-only mode.READ_ONLY_TOOLS = { "list-budgets", "list-accounts", "list-transactions", "list-categories", "list-payees", "list-scheduled-transactions", "get-financial-overview", "get-month-info", "lookup-payee-locations", }