home / mcp / blockscout mcp server

Blockscout MCP Server

Exposes Blockscout blockchain data via MCP for contextual AI access and analysis.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "blockscout-mcp-server": {
      "url": "https://mcp.blockscout.com/mcp",
      "headers": {
        "BLOCKSCOUT_DEV_JSON_RESPONSE": "true",
        "BLOCKSCOUT_MCP_ALLOWED_HOSTS": "your-tunnel-id.ngrok.io",
        "BLOCKSCOUT_MCP_ALLOWED_ORIGINS": "https://your-tunnel-id.ngrok.io",
        "BLOCKSCOUT_DISABLE_COMMUNITY_TELEMETRY": "true"
      }
    }
  }
}

The Blockscout MCP Server exposes blockchain data from Blockscout through the Model Context Protocol (MCP), enabling AI agents and development tools to query balances, tokens, NFTs, and contract metadata with context-aware APIs.

How to use

You connect your MCP client to the Blockscout MCP Server to access structured blockchain data within your AI workflows. Use the MCP endpoints to fetch account balances, token holdings, contract ABIs, block and transaction details, NFT collections, and token transfers. The server emphasizes efficient data access with features like pagination, data truncation indicators, and progress notifications for long-running operations. You can run the MCP server with inline HTTP support, enabling REST endpoints, and you can opt into development modes for local testing or tunneling during development.

How to install

Prerequisites: You need Python installed on your machine and basic command-line access.

# Run the server in stdio mode (default):
python -m blockscout_mcp_server

# Run the server in HTTP mode (with optional REST API):
python -m blockscout_mcp_server --http
python -m blockscout_mcp_server --http --rest

# Optional development/json mode for plain JSON responses (local testing):
export BLOCKSCOUT_DEV_JSON_RESPONSE=true
python -m blockscout_mcp_server --http

# Ngrok tunneling for development (with explicit host/origin):
export BLOCKSCOUT_MCP_ALLOWED_HOSTS="your-tunnel-id.ngrok.io"
export BLOCKSCOUT_MCP_ALLOWED_ORIGINS="https://your-tunnel-id.ngrok.io"
python -m blockscout_mcp_server --http

# Local Docker usage (HTTP mode):
# docker run --rm -p 8000:8000 ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --http-host 0.0.0.0

Additional configuration notes

You can enable the REST API alongside the MCP endpoint to provide a versioned API surface for clients. Use the HTTP mode with the REST flag to expose REST endpoints.

Tooling and integration tips

Integrate with client tools like Claude or Cursor by using the standard MCP server URL and port. For Claude Code, you can add Blockscout as an MCP server via the appropriate mcp add command, and for other clients, configure the MCP URL to point at the server’s HTTP endpoint.

Examples and showcases

A practical showcase is the Blockscout X-Ray GPT, which demonstrates intelligent blockchain analysis using the MCP server. You can explore how context-rich queries yield targeted insights across chains, including balances, token metadata, and contract data.

Security and privacy notes

If you opt into anonymous telemetry, the system collects non-personal usage data to help improve the service. Personal data, secrets, and private keys are not collected. You can opt out by setting BLOCKSCOUT_DISABLE_COMMUNITY_TELEMETRY=true.

Troubleshooting

If you encounter networking or accessibility issues, ensure your HTTP host binding is correct (localhost for local testing, 0.0.0.0 for external access) and that any required environment variables are set for development scenarios (ngrok, host whitelisting, etc.). If the REST API is enabled, verify that the correct port is open and reachable by your MCP client.

Notes on running in production

For production deployments, prefer a dedicated HTTP endpoint with proper host and TLS configuration. Use the REST API alongside the MCP endpoint if your clients require a stable, versioned surface. Monitor progress notifications for long-running tasks and tune page sizes to balance data accessibility with token usage.

Available tools

__unlock_blockchain_analysis__

Provides custom instructions for the MCP host to use the server and is a mandatory first step before other tools.

get_chains_list

Returns a list of all known chains.

get_address_by_ens_name

Converts an ENS domain name to its Ethereum address.

lookup_token_by_symbol

Searches for token addresses by symbol or name and returns multiple matches.

get_contract_abi

Retrieves the ABI for a smart contract.

inspect_contract_code

Retrieves source files of verified contracts.

get_address_info

Gets comprehensive information about an address including balance and token data.

get_tokens_by_address

Returns detailed ERC20 token holdings with metadata and market data.

get_block_number

Retrieves the block number and timestamp for a given time or the latest block.

get_transactions_by_address

Gets transactions for an address within a time range with optional method filtering.

get_token_transfers_by_address

Returns ERC-20 token transfers for an address in a time range.

nft_tokens_by_address

Retrieves NFT tokens owned by an address, grouped by collection.

get_block_info

Returns block information with optional transaction hashes.

get_transaction_info

Gets detailed transaction information with decoded inputs.

read_contract

Executes a read-only smart contract function and returns the result.

direct_api_call

Calls a curated raw Blockscout API endpoint for specialized data.