Blockscout MCP Server

Instructions

Implementation Reference

• blockscout_mcp_server/tools/block/get_latest_block.py:16-67 (handler)

  The core handler function implementing the get_latest_block tool. Fetches latest block data from Blockscout API using chain_id, processes the response, and returns a ToolResponse with LatestBlockData.
  @log_tool_invocation async def get_latest_block( chain_id: Annotated[str, Field(description="The ID of the blockchain")], ctx: Context ) -> ToolResponse[LatestBlockData]: """ Get the latest indexed block number and timestamp, which represents the most recent state of the blockchain. No transactions or token transfers can exist beyond this point, making it useful as a reference timestamp for other API calls. """ # noqa: E501 api_path = "/api/v2/main-page/blocks" # Report start of operation await report_and_log_progress( ctx, progress=0.0, total=2.0, message=f"Starting to fetch latest block info on chain {chain_id}...", ) base_url = await get_blockscout_base_url(chain_id) # Report progress after resolving Blockscout URL await report_and_log_progress( ctx, progress=1.0, total=2.0, message="Resolved Blockscout instance URL. Fetching latest block data...", ) response_data = await make_blockscout_request(base_url=base_url, api_path=api_path) # Report completion await report_and_log_progress( ctx, progress=2.0, total=2.0, message="Successfully fetched latest block data.", ) # The API returns a list. Extract data from the first item if response_data and isinstance(response_data, list) and len(response_data) > 0: first_block = response_data[0] # The main idea of this tool is to provide the latest block number of the chain. # The timestamp is provided to be used as a reference timestamp for other API calls. block_data = LatestBlockData( block_number=first_block.get("height"), timestamp=first_block.get("timestamp"), ) return build_tool_response(data=block_data) # Handle cases with no data by raising an error raise ValueError("Could not retrieve latest block data from the API.")
• blockscout_mcp_server/server.py:153-156 (registration)

  Registration of the get_latest_block tool in the FastMCP server instance with annotations and structured_output=False.
  mcp.tool( structured_output=False, annotations=create_tool_annotations("Get Latest Block"), )(get_latest_block)
• blockscout_mcp_server/models.py:36-41 (schema)

  Pydantic model defining the structure of the latest block data payload returned by the tool.
  class LatestBlockData(BaseModel): """Represents the essential data for the latest block.""" block_number: int = Field(description="The block number (height) in the blockchain") timestamp: str = Field(description="The timestamp when the block was mined (ISO format)")