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)

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.

Tool	Purpose
__unlock_blockchain_analysis__	Onboarding — usage rules. Call this first.
get_chains_list	List supported chains (bundled + custom).
get_address_info	Balance, type, and metadata for an address.
get_tokens_by_address	Token balances held by an address.
get_token_transfers_by_address	Token transfers involving an address.
get_transactions_by_address	Native transactions involving an address.
get_transaction_info	Full details for a transaction hash.
get_token_transfers_by_transaction	Token transfers within a transaction.
get_block_info	Details for a block by number or hash.
get_block_number	Latest block height for a chain.
get_logs	Event logs for an address (large data truncated).
get_contract_abi	ABI of a verified contract.
inspect_contract_code	Verified source code + compiler metadata.
nft_tokens_by_address	NFTs owned by an address.
lookup_token_by_symbol	Search tokens by symbol/name.
direct_api_call	Escape hatch for any Blockscout /api/v2 endpoint (size-capped).

Configuration

All environment variables are optional:

Variable	Default	Description
CHAINS_FILE	(unset)	Path to a JSON file of custom chains.
ONLY_CHAINS_FILE	false	When true, register only CHAINS_FILE chains (exclude bundled).
BLOCKSCOUT_TIMEOUT_MS	30000	Timeout for heavy list requests.
BLOCKSCOUT_LIGHT_TIMEOUT_MS	15000	Timeout for point lookups.
BLOCKSCOUT_MAX_RETRIES	3	Transport-error retries for GET.
BLOCKSCOUT_PAGE_SIZE	10	Page size hint.
BLOCKSCOUT_DIRECT_API_LIMIT	100000	Char cap on direct_api_call responses.

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