YNAB MCP Server

Instructions

Args:
    budget_id: The ID of the budget (use 'last-used' for default budget)
    category_id: The category ID

Returns:
    JSON string with category details including goals, budgeted amounts, activity, and balance

Implementation Reference

• src/ynab_mcp/server.py:67-81 (handler)

  MCP tool handler for get_category. Decorated with @mcp.tool() for automatic registration and schema derivation from signature/docstring. Delegates to YNABClient.get_category and returns JSON.

  @mcp.tool()
  async def get_category(budget_id: str, category_id: str) -> str:
      """Get a single category with full details including goal information.
  
      Args:
          budget_id: The ID of the budget (use 'last-used' for default budget)
          category_id: The category ID
  
      Returns:
          JSON string with category details including goals, budgeted amounts, activity, and balance
      """
      client = get_ynab_client()
      result = await client.get_category(budget_id, category_id)
      return json.dumps(result, indent=2)

• src/ynab_mcp/ynab_client.py:250-300 (helper)

  Core implementation in YNABClient that fetches single category via YNAB API GET /budgets/{budget_id}/categories/{category_id}, processes response with goal details, converts milliunits, and returns structured dict.

  async def get_category(self, budget_id: str, category_id: str) -> dict[str, Any]:
      """Get a single category with all details including goal information.
  
      Args:
          budget_id: The budget ID or 'last-used'
          category_id: The category ID
  
      Returns:
          Category dictionary with full details
  
      Raises:
          YNABValidationError: If parameters are invalid
          YNABAPIError: If API request fails
      """
      logger.debug(f"Getting category {category_id} for budget {budget_id}")
  
      # Validate inputs
      budget_id = validate_budget_id(budget_id)
  
      url = f"{self.api_base_url}/budgets/{budget_id}/categories/{category_id}"
      result = await self._make_request_with_retry("get", url)
  
      cat = result["data"]["category"]
  
      return {
          "id": cat["id"],
          "name": cat["name"],
          "category_group_id": cat.get("category_group_id"),
          "hidden": cat.get("hidden"),
          "note": cat.get("note"),
          "budgeted": cat.get("budgeted", 0) / MILLIUNITS_FACTOR if cat.get("budgeted") else 0,
          "activity": cat.get("activity", 0) / MILLIUNITS_FACTOR if cat.get("activity") else 0,
          "balance": cat.get("balance", 0) / MILLIUNITS_FACTOR if cat.get("balance") else 0,
          "goal_type": cat.get("goal_type"),
          "goal_target": cat.get("goal_target", 0) / MILLIUNITS_FACTOR
          if cat.get("goal_target")
          else 0,
          "goal_target_month": cat.get("goal_target_month"),
          "goal_percentage_complete": cat.get("goal_percentage_complete"),
          "goal_months_to_budget": cat.get("goal_months_to_budget"),
          "goal_under_funded": cat.get("goal_under_funded", 0) / MILLIUNITS_FACTOR
          if cat.get("goal_under_funded")
          else 0,
          "goal_overall_funded": cat.get("goal_overall_funded", 0) / MILLIUNITS_FACTOR
          if cat.get("goal_overall_funded")
          else 0,
          "goal_overall_left": cat.get("goal_overall_left", 0) / MILLIUNITS_FACTOR
          if cat.get("goal_overall_left")
          else 0,
      }

• src/ynab_mcp/server.py:67-67 (registration)

  The @mcp.tool() decorator registers the get_category function as an MCP tool.

  @mcp.tool()

• src/ynab_mcp/server.py:69-77 (schema)

  Tool schema derived from function signature (budget_id: str, category_id: str -> str) and docstring describing parameters and return value.

  """Get a single category with full details including goal information.
  
  Args:
      budget_id: The ID of the budget (use 'last-used' for default budget)
      category_id: The category ID
  
  Returns:
      JSON string with category details including goals, budgeted amounts, activity, and balance
  """