YNAB MCP Server

Instructions

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

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