yfinance_search

Instructions

Returns JSON with search results based on search_type:

- 'quotes': Array of securities with:
    - symbol: Ticker symbol
    - shortname/longname: Company name
    - quoteType: Security type (EQUITY, ETF, MUTUALFUND, etc.)
    - exchange: Exchange code
    - sector: Business sector
    - industry: Industry classification
    - score: Search relevance score

- 'news': Array of articles with:
    - uuid: Article identifier
    - title: Headline
    - publisher: News source
    - link: Article URL
    - providerPublishTime: Unix timestamp
    - relatedTickers: Array of related symbols
    - thumbnail: Image URLs

- 'all': Object with both 'quotes' and 'news' arrays

Use this to find ticker symbols, discover related securities, or search financial news.

Implementation Reference

• src/yfmcp/server.py:241-299 (handler)

  The async function 'search' that implements the yfinance_search tool logic. It takes a query string and search_type ('all', 'quotes', 'news'), calls yf.Search, and returns JSON results based on the search_type filter.

  async def search(
      query: Annotated[str, Field(description="Search query - company name, ticker symbol, or keywords")],
      search_type: Annotated[
          SearchType,
          Field(
              description="Filter results: 'all' (quotes + news), 'quotes' (stocks/ETFs only), or 'news' (articles only)"
          ),
      ],
  ) -> str:
      """Search Yahoo Finance for stocks, ETFs, and news articles.
  
      Returns JSON with search results based on search_type:
  
      - 'quotes': Array of securities with:
          - symbol: Ticker symbol
          - shortname/longname: Company name
          - quoteType: Security type (EQUITY, ETF, MUTUALFUND, etc.)
          - exchange: Exchange code
          - sector: Business sector
          - industry: Industry classification
          - score: Search relevance score
  
      - 'news': Array of articles with:
          - uuid: Article identifier
          - title: Headline
          - publisher: News source
          - link: Article URL
          - providerPublishTime: Unix timestamp
          - relatedTickers: Array of related symbols
          - thumbnail: Image URLs
  
      - 'all': Object with both 'quotes' and 'news' arrays
  
      Use this to find ticker symbols, discover related securities, or search financial news.
      """
      try:
          s = await asyncio.to_thread(yf.Search, query)
      except _RETRYABLE_YFINANCE_EXCEPTIONS as exc:
          return _create_retryable_error_response(f"searching for '{query}'", exc, {"query": query})
      except Exception as exc:
          return create_error_response(
              f"Search failed for '{query}'. Try simplifying your query or using different keywords.",
              error_code="API_ERROR",
              details={"query": query, "exception": str(exc)},
          )
  
      match search_type.lower():
          case "all":
              return dump_json(s.all)
          case "quotes":
              return dump_json(s.quotes)
          case "news":
              return dump_json(s.news)
          case _:
              return create_error_response(
                  f"Invalid search_type '{search_type}'. Valid options: 'all', 'quotes', 'news'.",
                  error_code="INVALID_PARAMS",
                  details={"search_type": search_type, "valid_options": ["all", "quotes", "news"]},
              )

• src/yfmcp/server.py:232-240 (registration)

  The @mcp.tool decorator that registers the function as the 'yfinance_search' MCP tool with readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=True.

  @mcp.tool(
      name="yfinance_search",
      annotations=ToolAnnotations(
          readOnlyHint=True,
          destructiveHint=False,
          idempotentHint=True,
          openWorldHint=True,
      ),
  )

• src/yfmcp/types.py:13-17 (schema)

  The SearchType Literal type definition used for the search_type parameter validation in the yfinance_search tool.

  SearchType = Literal[
      "all",
      "quotes",
      "news",
  ]

• src/yfmcp/utils.py:6-7 (helper)

  The dump_json helper function used by the search handler to serialize JSON results with proper encoding.

  def dump_json(payload: object) -> str:
      return json.dumps(payload, ensure_ascii=False, default=str)