MCP YNAB Server

Instructions

Implementation Reference

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

  The primary handler for the 'get_categories' MCP tool. It fetches categories from the YNAB API using CategoriesApi, processes them into groups, formats budgeted and activity amounts, and returns a Markdown table representation.
  @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 by get_categories to extract and normalize category data from either Category objects or dicts.
  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 by get_categories to format dollar amounts with signs and commas.
  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
• src/mcp_ynab/server.py:632-675 (registration)

  The @mcp.tool() decorator registers the get_categories function as an MCP tool with the name 'get_categories'.
  @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