You Need A Budget (YNAB) MCP

Instructions

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)]

• src/ynab_mcp_server/tool_models.py:97-98 (schema)

  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(),
  ),

• src/ynab_mcp_server/ynab_client.py:227-231 (helper)

  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",
  }