# 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.

> [!IMPORTANT]
> This is **not** the [official Blockscout MCP server](https://github.com/blockscout/mcp-server). It is a custom, independently
> built server maintained by an individual developer, and it is not affiliated with or endorsed by
> the Blockscout team.

## Quick start


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

```json
{
  "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).

```json
{
  "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`).

| Chain name | Chain ID | Blockscout instance |
| --- | --- | --- |
| `ethereum` | 1 | https://eth.blockscout.com |
| `optimism` | 10 | https://optimism.blockscout.com |
| `gnosis` | 100 | https://gnosis.blockscout.com |
| `base` | 8453 | https://base.blockscout.com |
| `arbitrum` | 42161 | https://arbitrum.blockscout.com |
| `scroll` | 534352 | https://scroll.blockscout.com |
| `sepolia` | 11155111 | https://eth-sepolia.blockscout.com |

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`:

```json
[
  { "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.

```bash
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