YNAB MCP Server

Instructions

Implementation Reference

• src/ynab_mcp/server.py:125-139 (handler)

  MCP tool handler function for get_budget_summary. Registers the tool via @mcp.tool() decorator, validates inputs via type hints and docstring, delegates to YNABClient, and serializes response to JSON.
  @mcp.tool() async def get_budget_summary(budget_id: str, month: str) -> str: """Get budget summary for a specific month. Args: budget_id: The ID of the budget (use 'last-used' for default budget) month: Month in YYYY-MM-DD format (e.g., 2025-01-01 for January 2025) Returns: JSON string with budget summary including income, budgeted amounts, and category details """ client = get_ynab_client() result = await client.get_budget_summary(budget_id, month) return json.dumps(result, indent=2)
• src/ynab_mcp/ynab_client.py:443-524 (helper)

  Core helper function in YNABClient that implements the business logic: validates inputs, fetches month data from YNAB API endpoint /budgets/{budget_id}/months/{month}, maps categories to groups, filters hidden/deleted, calculates aggregate totals (income, budgeted, activity, balance, to_be_budgeted), and returns structured dictionary with category details.
  async def get_budget_summary(self, budget_id: str, month: str) -> dict[str, Any]: """Get budget summary for a specific month. Uses direct API to get month-specific data since SDK doesn't support it. Args: budget_id: The budget ID or 'last-used' month: Month in YYYY-MM-DD format (e.g., 2025-01-01) Returns: Budget summary dictionary Raises: YNABValidationError: If parameters are invalid YNABAPIError: If API request fails """ logger.debug(f"Getting budget summary for {budget_id}, month {month}") # Validate inputs budget_id = validate_budget_id(budget_id) month = validate_date(month, "month") # Use direct API call to get month-specific budget data url = f"{self.api_base_url}/budgets/{budget_id}/months/{month}" result = await self._make_request_with_retry("get", url) month_data = result["data"]["month"] # Debug: Check what keys are available if "categories" not in month_data: raise YNABAPIError(f"Month data keys: {list(month_data.keys())}") # Get category groups to map category IDs to group names categories_response = self.client.categories.get_categories(budget_id) category_group_map = {} for group in categories_response.data.category_groups: for cat in group.categories: category_group_map[cat.id] = group.name # Calculate totals and collect category details total_budgeted = 0 total_activity = 0 total_balance = 0 categories = [] # Month data has a flat list of categories, not grouped # Filter out hidden and deleted categories filtered_categories = self._filter_categories(month_data.get("categories", [])) for category in filtered_categories: budgeted = category["budgeted"] / MILLIUNITS_FACTOR if category["budgeted"] else 0 activity = category["activity"] / MILLIUNITS_FACTOR if category["activity"] else 0 balance = category["balance"] / MILLIUNITS_FACTOR if category["balance"] else 0 total_budgeted += budgeted total_activity += activity total_balance += balance category_group_name = category_group_map.get(category["id"], "Unknown") categories.append( { "category_group": category_group_name, "category_name": category["name"], "budgeted": budgeted, "activity": activity, "balance": balance, } ) return { "month": month, "income": month_data["income"] / MILLIUNITS_FACTOR if month_data.get("income") else 0, "budgeted": total_budgeted, "activity": total_activity, "balance": total_balance, "to_be_budgeted": month_data["to_be_budgeted"] / MILLIUNITS_FACTOR if month_data.get("to_be_budgeted") else 0, "categories": categories, }
• src/ynab_mcp/server.py:125-125 (registration)

  The @mcp.tool() decorator registers the get_budget_summary function as an MCP tool with FastMCP, automatically generating schema from signature and docstring.
  @mcp.tool()
• src/ynab_mcp/server.py:127-135 (schema)

  Docstring provides input schema description (budget_id str, month str in YYYY-MM-DD) and output format (JSON string with summary details). Type hints reinforce schema.
  """Get budget summary for a specific month. Args: budget_id: The ID of the budget (use 'last-used' for default budget) month: Month in YYYY-MM-DD format (e.g., 2025-01-01 for January 2025) Returns: JSON string with budget summary including income, budgeted amounts, and category details """