Yahoo Finance MCP Server

Instructions

Implementation Reference

• src/yfmcp/server.py:168-187 (handler)

  The core handler function for the 'get_top' MCP tool. Registered via @mcp.tool() decorator. Dispatches to specific helper functions based on the top_type parameter using input schemas Sector and TopType.

  @mcp.tool()
  def get_top(
      sector: Annotated[Sector, Field(description="The sector to get")],
      top_type: Annotated[TopType, Field(description="Type of top companies to retrieve")],
      top_n: Annotated[int, Field(description="Number of top entities to retrieve (limit the results)")] = 10,
  ) -> str:
      """Get top entities (ETFs, mutual funds, companies, growth companies, or performing companies) in a sector."""
      match top_type:
          case "top_etfs":
              return get_top_etfs(sector, top_n)
          case "top_mutual_funds":
              return get_top_mutual_funds(sector, top_n)
          case "top_companies":
              return get_top_companies(sector, top_n)
          case "top_growth_companies":
              return get_top_growth_companies(sector, top_n)
          case "top_performing_companies":
              return get_top_performing_companies(sector, top_n)
          case _:
              return "Invalid top_type"

• src/yfmcp/types.py:10-16 (schema)

  Literal type defining the allowed values for the 'top_type' parameter in the get_top tool.

  TopType = Literal[
      "top_etfs",
      "top_mutual_funds",
      "top_companies",
      "top_growth_companies",
      "top_performing_companies",
  ]

• src/yfmcp/types.py:19-31 (schema)

  Literal type defining the allowed values for the 'sector' parameter in the get_top tool.

  Sector = Literal[
      "Basic Materials",
      "Communication Services",
      "Consumer Cyclical",
      "Consumer Defensive",
      "Energy",
      "Financial Services",
      "Healthcare",
      "Industrials",
      "Real Estate",
      "Technology",
      "Utilities",
  ]

• src/yfmcp/server.py:98-114 (helper)

  Helper function called by get_top for top_type='top_companies'. Fetches top companies DataFrame from yf.Sector and returns JSON.

  def get_top_companies(
      sector: Annotated[Sector, Field(description="The sector to get")],
      top_n: Annotated[int, Field(description="Number of top companies to retrieve")],
  ) -> str:
      """Get top companies in a sector with name, analyst rating, and market weight as JSON array."""
      if top_n < 1:
          return "top_n must be greater than 0"
  
      try:
          s = yf.Sector(sector)
          df = s.top_companies
      except Exception as e:
          return json.dumps({"error": f"Failed to get top companies for sector '{sector}': {e}"})
      if df is None:
          return json.dumps({"error": f"No top companies available for {sector} sector."})
      return df.iloc[:top_n].to_json(orient="records")