blockscout-mcp-server

A read-only stdio MCP server that gives AI agents multichain EVM on-chain data — addresses, transactions, blocks, logs, tokens, NFTs, and contract source — through the Blockscout REST API.

Quick start

npx downloads the published package and runs it — nothing to install manually. Works from any project;

{
  "mcpServers": {
    "blockscout": {
      "command": "npx",
      "args": ["-y", "blockscout-mcp-server"],
    }
  }
}

point CHAINS_FILE at that project's chains file (a relative ./chains.json resolves against the client's working directory).

{
  "mcpServers": {
    "blockscout": {
      "command": "npx",
      "args": ["-y", "blockscout-mcp-server"],
      "env": {
        "CHAINS_FILE": "./chains.json",
        "ONLY_CHAINS_FILE": "true"
      }
    }
  }
}

The chain registry and env are read once at startup. After changing config or code, restart (reconnect) the server in your MCP client. A ready-to-edit .mcp.example.json is included.

Supported chains

These chains are registered out of the box from the bundled snapshot (src/chains/bundled.json) — no configuration required. The chain argument of any tool accepts either the name (ethereum) or the numeric chain ID (1).

Call the get_chains_list tool to see the chains actually registered on a running server.

Custom chains

Point CHAINS_FILE at a JSON file describing extra chains (or overriding bundled ones). Each entry needs a name, chainId, and Blockscout instance url:

[
  { "name": "my-l2", "chainId": 42, "url": "https://scan.my-l2.io" }
]

If CHAINS_FILE is set but the file is missing or malformed, the server exits immediately (fail-fast).

Set ONLY_CHAINS_FILE=true to register only the chains from CHAINS_FILE and exclude the bundled snapshot entirely. It requires CHAINS_FILE to be set (otherwise no chains would exist and the server fails fast). The default (false) merges bundled chains with CHAINS_FILE.

Local development

The MCP Inspector is wired up as a dev dependency, so you can walk through the MCP handshake and call tools by hand without hooking the server into a real client.

git clone https://github.com/imelon2/blockscout-mcp-server.git
cd blockscout-mcp-server
pnpm install
pnpm run inspect

pnpm run inspect builds first, then opens the Inspector UI — pick the stdio transport and point it at node dist/index.js. Two shortcuts:

License

MIT