You Need A Budget (YNAB) MCP

Instructions

Implementation Reference

• src/ynab_mcp_server/server.py:560-578 (handler)

  The core handler function that executes the 'get-month-info' tool. It validates input using GetMonthInfoInput, resolves the budget ID, fetches either a specific month's details or a list of all months via ynab_client, formats the data, and returns it as text content.

  elif name == "get-month-info":
      args = GetMonthInfoInput.model_validate(arguments or {})
      budget_id = await _get_budget_id(args.model_dump())
  
      if args.month:
          # Get a single month
          month_detail = await ynab_client.get_budget_month(budget_id, args.month)
          result_dict = month_detail.to_dict()
          text_output = f"Details for month {args.month}:\n{json.dumps(result_dict, indent=2, default=str)}"
      else:
          # List all months
          months = await ynab_client.get_budget_months(budget_id)
          month_list = "\n".join(
              f"- Month: {m.month}, Budgeted: {m.budgeted / 1000:.2f}, Activity: {m.activity / 1000:.2f}, To Be Budgeted: {m.to_be_budgeted / 1000:.2f}"
              for m in months
          )
          text_output = f"Available months for budget {budget_id}:\n{month_list}"
  
      return [types.TextContent(type="text", text=text_output)]

• src/ynab_mcp_server/tool_models.py:336-340 (schema)

  Pydantic model defining the input schema for the get-month-info tool. Inherits from BudgetIdInput (which provides optional budget_id) and adds an optional 'month' field.

  class GetMonthInfoInput(BudgetIdInput):
      month: Optional[str] = Field(
          None, description="The month to retrieve in YYYY-MM-DD format. If not provided, all months will be listed."
      )

• src/ynab_mcp_server/server.py:120-124 (registration)

  Registers the 'get-month-info' tool in the list_tools() handler, specifying its name, description, and input schema derived from GetMonthInfoInput.

  types.Tool(
      name="get-month-info",
      description="Get detailed budget information for a single month, including age of money and total amounts budgeted, spent, and available. Call this to check the monthly budget's status before making changes.",
      inputSchema=GetMonthInfoInput.model_json_schema(),
  ),

• src/ynab_mcp_server/tool_models.py:7-11 (schema)

  Base Pydantic model used by GetMonthInfoInput (and many other tools) providing the optional 'budget_id' field.

  class BudgetIdInput(BaseModel):
      budget_id: Optional[str] = Field(
          None,
          description="The ID of the budget. If not provided, the default budget will be used.",
      )

• src/ynab_mcp_server/server.py:142-152 (helper)

  Helper function used by get-month-info (and other tools) to resolve the budget_id from input arguments, settings, or by fetching the default budget.

  async def _get_budget_id(arguments: dict | None) -> str:
      """Gets the budget_id from arguments, settings, or falls back to the default budget."""
      if settings.ynab_default_budget_id:
          return settings.ynab_default_budget_id
  
      if arguments and "budget_id" in arguments and arguments["budget_id"]:
          return arguments["budget_id"]
  
      budget = await ynab_client.get_default_budget()
      return budget.id