kukapay/findblock-mcp

FindBlock MCP

An MCP server for retrieving block numbers by timestamp, enabling fast and precise on-chain data queries.

Features

• Block Timestamp Search: Find blocks before/after specific timestamps with optional inclusivity.
• Chain Discovery: List and retrieve details for thousands of EVM chains.
• RPC Proxying: Forward JSON-RPC calls to optimal endpoints for any chain.

Requirements

• Python 3.10+
• uv for dependency management (recommended)

Installation

1. Clone & Install:

   git clone https://github.com/kukapay/findblock-mcp.git
   cd findblock-mcp
   uv sync 
   

2. Install to Claude Desktop:

   Install the server as a Claude Desktop application:

   uv run mcp install main.py --name "Find Block"
   

   Configuration file as a reference:

   {
      "mcpServers": {
          "Find Block": {
              "command": "uv",
              "args": [ "--directory", "/path/to/findblock-mcp", "run", "main.py" ]
          }
      }
   }
   

   Replace /path/to/findblock-mcp with your actual installation path.

Usage

Once installed (e.g., in Claude Desktop), interact with the tools via natural language prompts. The LLM will automatically discover and invoke them. Below are detailed tool descriptions with parameters and examples.

Tools

1. find_block_before(chain_id: int, timestamp: int, inclusive: bool = False)

Locates the block immediately before (or at, if inclusive=True) a given UNIX timestamp. Returns Markdown-formatted block details including number, timestamp, hash, and parent hash.

Parameters:

• chain_id (int, required): The EVM Chain ID.
• timestamp (int, required): UNIX timestamp (seconds since epoch).
• inclusive (bool, optional, default=False): Include the block at the exact timestamp if it matches.

Example Prompt:

Find the last Ethereum block before January 1, 2024.

Expected Output:

### Block Details (Before Timestamp)
- **Number:** 19300000
- **Timestamp:** 1704067199 (UNIX)
- **Hash:** `0xabc123...def456`
- **Parent Hash:** `0xdef789...ghi012`

2. find_block_after(chain_id: int, timestamp: int, inclusive: bool = False)

Locates the block immediately after (or at, if inclusive=True) a given UNIX timestamp. Returns Markdown-formatted block details including number, timestamp, hash, and parent hash.

Parameters:

• chain_id (int, required): The EVM Chain ID.
• timestamp (int, required): UNIX timestamp (seconds since epoch).
• inclusive (bool, optional, default=False): Include the block at the exact timestamp if it matches.

Example Prompt:

What's the first Polygon block after March 15, 2023, 12:00 UTC?

Expected Output:

### Block Details (After Timestamp)
- **Number:** 45000000
- **Timestamp:** 1678867201 (UNIX)
- **Hash:** `0x123abc...456def`
- **Parent Hash:** `0x789ghi...012jkl`

3. list_chains()

Retrieves a list of all available EVM chains supported by FindBlock, formatted as a Markdown bullet list with chain names and IDs.

Parameters:

• None

Example Prompt:

Show me a list of popular EVM chains I can query.

Expected Output:

### Available Chains

- **Ethereum** (Chain ID: 1)
- **Binance Smart Chain** (Chain ID: 56)
- **Polygon** (Chain ID: 137)
- **Avalanche C-Chain** (Chain ID: 43114)
- ... (truncated for brevity; full list includes 1,000+ chains)

4. get_chain(chain_id: int)

Fetches detailed information for a specific EVM chain by its Chain ID, returned as Markdown with name and ID.

Parameters:

• chain_id (int, required): The EVM Chain ID (e.g., 1 for Ethereum Mainnet).

Example Prompt:

Tell me about Ethereum Mainnet.

Expected Output:

### Chain Details

- **Name:** Ethereum
- **Chain ID:** 1

5. rpc_call(chain_id: int, method: str, params: List[Any] = [], request_id: int = 1)

Proxies an EVM JSON-RPC request to the best-performing RPC endpoint for the specified chain. Supports any standard EVM method (e.g., eth_blockNumber, eth_getBalance). Returns Markdown with success results or error details.

Parameters:

• chain_id (int, required): The EVM Chain ID.
• method (str, required): The JSON-RPC method name.
• params (List[Any], optional, default=[]): Array of parameters for the method.
• request_id (int, optional, default=1): Unique ID for the request.

Example Prompt:

What's the current block number on Binance Smart Chain?

Expected Output (success case):

### RPC Result

**ID:** 42
**Result:** 
"0x1a2b3c4d"

License

This project is licensed under the MIT License - see the file for details.