Blockscout MCP Server

Instructions

Search for token addresses by symbol or name. Returns multiple potential
matches based on symbol or token name similarity. Only the first
``TOKEN_RESULTS_LIMIT`` matches from the Blockscout API are returned.

Implementation Reference

• blockscout_mcp_server/tools/search/lookup_token_by_symbol.py:19-86 (handler)

  The core handler function that executes the lookup_token_by_symbol tool logic. It queries the Blockscout search API, processes results, limits to 7 items, and returns a ToolResponse with TokenSearchResult objects.

  @log_tool_invocation
  async def lookup_token_by_symbol(
      chain_id: Annotated[str, Field(description="The ID of the blockchain")],
      symbol: Annotated[str, Field(description="Token symbol or name to search for")],
      ctx: Context,
  ) -> ToolResponse[list[TokenSearchResult]]:
      """
      Search for token addresses by symbol or name. Returns multiple potential
      matches based on symbol or token name similarity. Only the first
      ``TOKEN_RESULTS_LIMIT`` matches from the Blockscout API are returned.
      """
      api_path = "/api/v2/search"
      params = {"q": symbol}
  
      await report_and_log_progress(
          ctx,
          progress=0.0,
          total=2.0,
          message=f"Starting token search for '{symbol}' on chain {chain_id}...",
      )
  
      base_url = await get_blockscout_base_url(chain_id)
  
      await report_and_log_progress(
          ctx,
          progress=1.0,
          total=2.0,
          message="Resolved Blockscout instance URL. Searching for tokens...",
      )
  
      response_data = await make_blockscout_request(base_url=base_url, api_path=api_path, params=params)
  
      await report_and_log_progress(
          ctx,
          progress=2.0,
          total=2.0,
          message="Successfully completed token search.",
      )
  
      all_items = response_data.get("items", [])
      notes = None
  
      if len(all_items) > TOKEN_RESULTS_LIMIT:
          notes = [
              (
                  f"The number of results exceeds the limit of {TOKEN_RESULTS_LIMIT}. "
                  f"Only the first {TOKEN_RESULTS_LIMIT} are shown."
              )
          ]
  
      items_to_process = all_items[:TOKEN_RESULTS_LIMIT]
  
      search_results = [
          TokenSearchResult(
              address=item.get("address_hash", ""),
              name=item.get("name", ""),
              symbol=item.get("symbol", ""),
              token_type=item.get("token_type", ""),
              total_supply=item.get("total_supply"),
              circulating_market_cap=item.get("circulating_market_cap"),
              exchange_rate=item.get("exchange_rate"),
              is_smart_contract_verified=item.get("is_smart_contract_verified", False),
              is_verified_via_admin_panel=item.get("is_verified_via_admin_panel", False),
          )
          for item in items_to_process
      ]
  
      return build_tool_response(data=search_results, notes=notes)

• blockscout_mcp_server/server.py:169-172 (registration)

  MCP tool registration for lookup_token_by_symbol, including annotations and structured_output=False.

  mcp.tool(
      structured_output=False,
      annotations=create_tool_annotations("Lookup Token by Symbol"),
  )(lookup_token_by_symbol)

• blockscout_mcp_server/models.py:175-188 (schema)

  Pydantic model defining the structure of each TokenSearchResult in the tool's output data list.

  # --- Model for lookup_token_by_symbol Data Payload ---
  class TokenSearchResult(BaseModel):
      """Represents a single token found by a search query."""
  
      address: str = Field(description="The contract address of the token.")
      name: str = Field(description="The full name of the token (e.g., 'USD Coin').")
      symbol: str = Field(description="The symbol of the token (e.g., 'USDC').")
      token_type: str = Field(description="The token standard (e.g., 'ERC-20').")
      total_supply: str | None = Field(description="The total supply of the token.")
      circulating_market_cap: str | None = Field(description="The circulating market cap, if available.")
      exchange_rate: str | None = Field(description="The current exchange rate, if available.")
      is_smart_contract_verified: bool = Field(description="Indicates if the token's contract is verified.")
      is_verified_via_admin_panel: bool = Field(description="Indicates if the token is verified by the Blockscout team.")

• blockscout_mcp_server/api/routes.py:335-335 (registration)

  REST API route registration for the lookup_token_by_symbol tool endpoint (/v1/lookup_token_by_symbol).

  _add_v1_tool_route(mcp, "/lookup_token_by_symbol", lookup_token_by_symbol_rest)

• blockscout_mcp_server/api/routes.py:174-179 (helper)

  REST wrapper function that calls the main tool handler with extracted parameters from the HTTP request.

  @handle_rest_errors
  async def lookup_token_by_symbol_rest(request: Request) -> Response:
      """REST wrapper for the lookup_token_by_symbol tool."""
      params = extract_and_validate_params(request, required=["chain_id", "symbol"], optional=[])
      tool_response = await lookup_token_by_symbol(**params, ctx=get_mock_context(request))
      return JSONResponse(tool_response.model_dump())