ynab_get_categories

Instructions

Implementation Reference

• src/ynab_mcp_server/server.py:162-205 (handler)

  The MCP tool handler function that lists all categories in a budget. It calls client.get_categories(), formats the output as a markdown table with budgeted/spent/available columns, and skips hidden/deleted/internal categories.

  @mcp.tool(
      name="ynab_get_categories",
      annotations={
          "title": "List Categories",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": False,
      }
  )
  async def ynab_get_categories(params: GetCategoriesInput) -> str:
      """List all category groups and categories with budgeted amounts and balances."""
      try:
          async with YNABClient() as client:
              category_groups = await client.get_categories(params.budget_id)
          
          result = "## Budget Categories\n\n"
          
          for group in category_groups:
              if group.get("hidden") or group.get("deleted"):
                  continue
              if group["name"] in ["Internal Master Category", "Credit Card Payments"]:
                  continue
                  
              result += f"### {group['name']}\n\n"
              result += "| Category | Budgeted | Spent | Available |\n"
              result += "|----------|----------|-------|----------|\n"
              
              for cat in group.get("categories", []):
                  if cat.get("hidden") or cat.get("deleted"):
                      continue
                      
                  budgeted = format_currency(cat.get("budgeted", 0))
                  activity = format_currency(cat.get("activity", 0))
                  balance = format_currency(cat.get("balance", 0))
                  
                  result += f"| {cat['name']} | {budgeted} | {activity} | {balance} |\n"
                  result += f"| ↳ ID: `{cat['id']}` | | | |\n"
              
              result += "\n"
          
          return result
      except Exception as e:
          return format_error(e)

• src/ynab_mcp_server/models.py:59-61 (schema)

  Pydantic input model for ynab_get_categories. Inherits from BudgetIdInput which provides a budget_id field (default 'last-used').

  class GetCategoriesInput(BudgetIdInput):
      """Input for listing all categories in a budget."""
      pass

• src/ynab_mcp_server/server.py:162-171 (registration)

  The @mcp.tool decorator registering 'ynab_get_categories' with FastMCP, including annotations for readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.

  @mcp.tool(
      name="ynab_get_categories",
      annotations={
          "title": "List Categories",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": False,
      }
  )

• src/ynab_mcp_server/api.py:226-229 (helper)

  The API client method that makes the actual HTTP GET request to YNAB's /budgets/{budget_id}/categories endpoint and returns category groups.

  async def get_categories(self, budget_id: str) -> List[Dict[str, Any]]:
      """Get all category groups and categories for a budget."""
      response = await self._request("GET", f"/budgets/{budget_id}/categories")
      return response["data"]["category_groups"]