Blockscout MCP

Blockscout MCP Server

The Model Context Protocol (MCP) is an open protocol designed to allow AI agents, IDEs, and automation tools to consume, query, and analyze structured data through context-aware APIs.

This server wraps Blockscout APIs and exposes blockchain data—balances, tokens, NFTs, contract metadata—via MCP so that AI agents and tools (like Claude, Cursor, or IDEs) can access and analyze it contextually.

Key Features:

• Contextual blockchain data access for AI tools
• Multi-chain support via Blockscout PRO API configuration with Chainscout metadata enrichment
• Versioned REST API: Provides a standard, web-friendly interface to all MCP tools. See API.md for full documentation.
• Custom instructions for MCP host to use the server
• Intelligent context optimization to conserve LLM tokens while preserving data accessibility
• Smart response slicing with configurable page sizes to prevent context overflow
• Opaque cursor pagination using Base64URL-encoded strings instead of complex parameters
• Automatic truncation of large data fields with clear indicators and access guidance
• Standardized ToolResponse model with structured JSON responses and follow-up instructions
• Enhanced observability with MCP progress notifications and periodic updates for long-running operations

Enhanced Analysis with Agent Skills

For more powerful and efficient blockchain analysis, install the Blockscout Analysis skill from the agent-skills repository. This skill provides AI agents with structured guidance for execution strategies, response handling, security best practices, and workflow orchestration.

Learn more: See the agent-skills README for full capabilities and installation instructions.

Configuring MCP Clients

Blockscout PRO API Key

Configuring the Blockscout MCP server with an AI agent requires a Blockscout PRO API key. Most of the data tools route their requests through the authenticated Blockscout PRO API gateway, so without a valid key those tools fail fast before making any upstream request.

To obtain a key, register on the Blockscout Developer Portal (the free tier does not require a credit card) and generate an API key; keys are prefixed proapi_. Then supply it when configuring your client, as shown in the sections below.

Claude Setup (Web, Desktop, Cowork) - Recommended

The easiest way to use the Blockscout MCP server with Claude is the official hosted server: a native, managed installation experience with automatic updates and nothing to run yourself. Add it as a Custom Connector with your own PRO API key. Claude sends the key on every request in an x-api-key header, which the server accepts as an alias for its Blockscout-MCP-Pro-Api-Key header.

1. Open Claude and go to Customize > Connectors. On Team and Enterprise plans an organization Owner does this under Organization settings > Connectors.
2. Click Add custom connector. Set the name to Blockscout and the URL to https://mcp.blockscout.com/mcp, then continue.
3. Leave Authentication as None (Claude detects it). A warning that the connector has no credentials is expected: the key is supplied in the next step.
4. Open Request headers, select x-api-key from the list, and paste your PRO API key as the value. Pick exactly this name; the server does not read the other similar-looking names in the list.
5. Click Add.

Note: The Request headers section is in beta and is not yet available to every organization. If your dialog does not show it, use the Connectors Directory below.

Note: On Team and Enterprise plans the key is entered once by the Owner and shared by the whole organization. Authentication settings cannot be edited after a connector is added: to change the key, remove the connector and add it again.

Using Claude Connectors Directory

If the Custom Connector dialog has no Request headers section, install the Blockscout connector from the official Anthropic Connectors Directory. It connects to the same hosted server but uses a shared access key.

Installation

Option 1: Direct Link

Visit claude.com/connectors/blockscout and click links in "Used in" section to install the Blockscout connector.

Option 2: Via Settings

1. Open Claude (Web or Desktop app)
2. Go to Settings > Connectors > Browse connectors
3. Search for "Blockscout"
4. Click "Connect" to install

Limitations: Due to the use of a shared access key, there may be restrictions on connector access and capabilities.

Claude Code Setup

Pass your PRO API key via the Blockscout-MCP-Pro-Api-Key header when adding the server:

claude mcp add --transport http blockscout https://mcp.blockscout.com/mcp \

--header "Blockscout-MCP-Pro-Api-Key: proapi_your_key_here"

After running this command, Blockscout will be available as an MCP server in Claude Code, allowing you to access and analyze blockchain data directly from your coding environment.

ChatGPT Apps Setup

Install the Blockscout app from the ChatGPT Apps marketplace:

1. Open the Blockscout app page (or search for "Blockscout" in the ChatGPT Apps directory).
2. Click "Connect" to enable the app for your ChatGPT account.

Codex App Setup

1. Open Codex and go to Settings > MCP Servers > Add server.
2. Set Name to Blockscout, select the Streamable HTTP tab, and set URL to https://mcp.blockscout.com/mcp.
3. Under Headers, add a header with key Blockscout-MCP-Pro-Api-Key and value proapi_your_key_here.
4. Save and restart the Codex app.

Codex CLI Setup

Codex CLI cannot attach a custom header from the command line, so configure it in two steps:

1. Scaffold the server entry:

   codex mcp add Blockscout --url https://mcp.blockscout.com/mcp

1. Edit ~/.codex/config.toml to add the PRO API key header and enable the streamable-HTTP MCP client (required for remote MCP servers to connect). The resulting configuration should look like this:

   [features]

experimental_use_rmcp_client = true

[mcp_servers.Blockscout] url = "https://mcp.blockscout.com/mcp" http_headers = { "Blockscout-MCP-Pro-Api-Key" = "proapi_your_key_here" }

Cursor Setup

Add the server to your Cursor MCP configuration — either the project-level .cursor/mcp.json or the global ~/.cursor/mcp.json — supplying your PRO API key via the Blockscout-MCP-Pro-Api-Key header:

{

"mcpServers": { "blockscout": { "url": "https://mcp.blockscout.com/mcp", "timeout": 180000, "headers": { "Blockscout-MCP-Pro-Api-Key": "proapi_your_key_here" } } } }

Local Development Setup (For Developers)

If you want to run the server locally for development purposes:

{

"mcpServers": { "blockscout": { "command": "docker", "args": [ "run", "--rm", "-i", "ghcr.io/blockscout/mcp-server:latest" ] } } }

Technical details

Refer to SPEC.md for the technical details.

Repository Structure

Refer to AGENTS.md for the repository structure.

Testing

Refer to TESTING.md for comprehensive instructions on running both unit and integration tests.

Tool Descriptions

1. __unlock_blockchain_analysis__() - Initializes a Blockscout MCP session: returns server reference data, the blockscout-analysis skill pointer, and the URI resolution rule. Call it once per session, before any other tool.
2. get_chains_list(query=None) - Returns a list of supported chains, with optional filtering by name, chain ID, native currency, or ecosystem.
3. get_address_by_ens_name(name) - Converts an ENS domain name to its corresponding Ethereum address.
4. lookup_token_by_symbol(chain_id, symbol) - Searches for token addresses by symbol or name, returning multiple potential matches.
5. get_contract_abi(chain_id, address) - Retrieves the ABI (Application Binary Interface) for a smart contract.
6. inspect_contract_code(chain_id, address, file_name=None) - Allows getting the source files of verified contracts.
7. get_address_info(chain_id, address) - Gets comprehensive information about an address including balance, ENS association, contract status, token details, and public tags.
8. get_tokens_by_address(chain_id, address, cursor=None) - Returns detailed ERC20 token holdings for an address with enriched metadata and market data.
9. get_block_number(chain_id, [datetime]) - Retrieves the block number and timestamp for a specific date/time or the latest block.
10. get_transactions_by_address(chain_id, address, age_from, age_to, methods, cursor=None) - Gets transactions for an address within a specific time range with optional method filtering.
11. get_token_transfers_by_address(chain_id, address, age_from, age_to, token, cursor=None) - Returns ERC-20 token transfers for an address within a specific time range.
12. nft_tokens_by_address(chain_id, address, cursor=None) - Retrieves NFT tokens owned by an address, grouped by collection.
13. get_block_info(chain_id, number_or_hash, include_transactions=False) - Returns block information including timestamp, gas used, burnt fees, and transaction count. Can optionally include a list of transaction hashes.
14. get_transaction_info(chain_id, hash, include_raw_input=False) - Gets comprehensive transaction information with decoded input parameters and detailed token transfers.
15. read_contract(chain_id, address, abi, function_name, args='[]', block='latest') - Executes a read-only smart contract function and returns its result. The abi argument is a JSON object describing the specific function's signature.
16. direct_api_call(chain_id, endpoint_path, query_params=None, cursor=None, method='GET', json_body=None) - Calls a raw Blockscout API endpoint for advanced or chain-specific data. Supports GET (default) and POST requests with JSON body.

Example Prompts for AI Agents

Is any approval set for OP token on Optimism chain by `zeaver.eth`?

Calculate the total gas fees paid on Ethereum by address `0xcafe...cafe` in May 2025.

Which 10 most recent logs were emitted by `0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7`

before Nov 08 2024 04:21:35 AM (-06:00 UTC)?

Tell me more about the transaction `0xf8a55721f7e2dcf85690aaf81519f7bc820bc58a878fa5f81b12aef5ccda0efb`

on Redstone rollup.

Is there any blacklisting functionality of USDT token on Arbitrum One?

What is the latest block on Gnosis Chain and who is the block minter?

Were any funds moved from this minter recently?

When the most recent reward distribution of Kinto token was made to the wallet

0x7D467D99028199D99B1c91850C4dea0c82aDDF52 in Kinto chain?

Which methods of `0x1c479675ad559DC151F6Ec7ed3FbF8ceE79582B6` on the Ethereum 

mainnet could emit SequencerBatchDelivered?

What is the most recent executed cross-chain message sent from the Arbitrum Sepolia

rollup to the base layer?

Development & Deployment

Local Installation

Clone the repository and install dependencies:

git clo