blockscout-mcp-server

A read-only Model Context Protocol (MCP) server that queries multichain EVM on-chain data through the Blockscout REST API. It runs over stdio and is designed for LLM clients (Claude Desktop, Cursor, etc.).

• Free & open source — calls public per-instance Blockscout REST APIs directly (no paid gateway, no API key).

• Read-only — never signs or sends transactions.

• Multichain — a bundled chain registry plus your own custom chains via a JSON file.

• LLM-friendly — every tool returns a standardized envelope with opaque cursor pagination and large-field truncation.

Requirements

• Node.js >= 24

• pnpm (for development)

Related MCP server: Onesource MCP

Install

The server runs over stdio: your MCP client launches it as a subprocess. Pick one of the following ways to point the command/args at it. env is optional in every case — without CHAINS_FILE only the bundled chains are available.

From npm (recommended)

npx downloads the published package and runs it — nothing to install manually. Works from any project; 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"
      }
    }
  }
}

From source (local development)

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

{
  "mcpServers": {
    "blockscout": {
      "command": "node",
      "args": ["/absolute/path/to/blockscout-mcp-server/dist/index.js"],
      "env": { "CHAINS_FILE": "/absolute/path/to/chains.json" }
    }
  }
}

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.

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.

Tools

All tools take a chain argument (a name like "ethereum" or a numeric chain ID like "1"). Paginated tools accept a cursor and return pagination.next_cursor when more results exist.

Configuration

All environment variables are optional:

Development

pnpm install
pnpm build        # tsc + copy assets to dist/
pnpm test         # unit tests (network mocked)
pnpm dev          # tsc --watch

Testing

• Unit tests run by default and mock all network access.

• Integration tests (real Blockscout calls) live under tests/integration/ and only run when RUN_INTEGRATION=1 is set:

  RUN_INTEGRATION=1 pnpm test

License

MIT