MCP YNAB Server

Instructions

Implementation Reference

• src/mcp_ynab/server.py:632-675 (handler)

  The primary handler for the 'get_categories' MCP tool. It is decorated with @mcp.tool(), fetches category groups from the YNAB API using CategoriesApi, processes the data with helper functions, builds Markdown tables for each category group, and returns the formatted string.

  @mcp.tool()
  async def get_categories(budget_id: str) -> str:
      """List all transaction categories for a given YNAB budget in Markdown format."""
      async with await get_ynab_client() as client:
          categories_api = CategoriesApi(client)
          response = categories_api.get_categories(budget_id)
          groups = response.data.category_groups
  
          markdown = "# YNAB Categories\n\n"
          headers = ["Category ID", "Category Name", "Budgeted", "Activity"]
          align = ["left", "left", "right", "right"]
  
          for group in groups:
              if isinstance(group, CategoryGroupWithCategories):
                  categories_list = group.categories
                  group_name = group.name
              else:
                  group_dict = cast(Dict[str, Any], group.to_dict())
                  categories_list = group_dict["categories"]
                  group_name = group_dict["name"]
  
              if not categories_list:
                  continue
  
              markdown += f"## {group_name}\n\n"
              rows = []
  
              for category in categories_list:
                  cat_id, name, budgeted, activity = _process_category_data(category)
                  budgeted_dollars = float(budgeted) / 1000 if budgeted else 0
                  activity_dollars = float(activity) / 1000 if activity else 0
  
                  rows.append(
                      [
                          cat_id,
                          name,
                          _format_dollar_amount(budgeted_dollars),
                          _format_dollar_amount(activity_dollars),
                      ]
                  )
  
              table_md = _build_markdown_table(rows, headers, align)
              markdown += table_md + "\n"
          return markdown

• src/mcp_ynab/server.py:618-624 (helper)

  Helper function used exclusively in get_categories to extract and standardize category information (ID, name, budgeted amount, activity) from either Category objects or dictionaries.

  def _process_category_data(category: Category | Dict[str, Any]) -> tuple[str, str, float, float]:
      """Process category data and return tuple of (id, name, budgeted, activity)."""
      if isinstance(category, Category):
          return category.id, category.name, category.budgeted, category.activity
      cat_dict = cast(Dict[str, Any], category)
      return cat_dict["id"], cat_dict["name"], cat_dict["budgeted"], cat_dict["activity"]

• src/mcp_ynab/server.py:626-630 (helper)

  Helper function used in get_categories to format dollar amounts (converting from dollars, adding $ sign, commas, and negative sign if applicable).

  def _format_dollar_amount(amount: float) -> str:
      """Format a dollar amount with proper sign and formatting."""
      amount_str = f"${abs(amount):,.2f}"
      return f"-{amount_str}" if amount < 0 else amount_str