mcp-server

# Blockscout MCP Server

[![smithery badge](https://smithery.ai/badge/@blockscout/mcp-server)](https://smithery.ai/server/@blockscout/mcp-server)

<a href="https://glama.ai/mcp/servers/@blockscout/mcp-server">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@blockscout/mcp-server/badge" alt="Blockscout Server MCP server" />
</a>

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](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](https://github.com/blockscout/agent-skills). 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](https://github.com/blockscout/agent-skills) 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](https://dev.blockscout.com) (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.

### Using Claude Connectors Directory - Recommended

The easiest way to use the Blockscout MCP server with Claude (Web, Desktop, and Code) is through the official [Anthropic Connectors Directory](https://claude.com/connectors). This provides a native, managed installation experience with automatic updates.

#### Installation

##### Option 1: Direct Link

Visit [claude.com/connectors/blockscout](https://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

> **Note:** Connectors require a paid Claude plan (Pro, Team, Max, or Enterprise).

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

### Claude Desktop Setup

To use the official Blockscout MCP server with your own PRO API key in Claude Desktop, choose one of the following options:

#### Option 1: MCP Bundle (MCPB) — Recommended

**Best for:** Easy installation and automatic updates.

1. Download the latest `blockscout-mcp.mcpb` from [GitHub releases](https://github.com/blockscout/mcp-server/releases).
2. Double-click the `.mcpb` file to install it in Claude Desktop.
3. Configure your Blockscout PRO API key when prompted.
4. The extension automatically connects to the hosted Blockscout MCP service.

#### Option 2: Docker Proxy

> **Note:** Docker is required for this setup.

**Best for:** Users comfortable with command-line tools and custom configurations.

1. Open Claude Desktop and click on Settings
2. Navigate to the "Developer" section
3. Click "Edit Config"
4. Open the file `claude_desktop_config.json` and configure the server:
  
    ```json
    {
      "mcpServers": {
        "blockscout": {
          "command": "docker",
          "args": [
            "run",
            "--rm",
            "-i",
            "sparfenyuk/mcp-proxy:latest",
            "--transport",
            "streamablehttp",
            "--headers",
            "Blockscout-MCP-Pro-Api-Key: proapi_your_key_here",
            "https://mcp.blockscout.com/mcp"
          ]
        }
      }
    }
    ```

5. Save the file and restart Claude Desktop

### Claude Code Setup

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

```sh
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](https://chatgpt.com/apps?q=Blockscout):

1. Open the [Blockscout app page](https://chatgpt.com/apps/blockscout-blockchain-data/asdk_app_69a880b0d024819182db60f36cb48420) (or search for "Blockscout" in the [ChatGPT Apps directory](https://chatgpt.com/apps?q=Blockscout)).
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:

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

2. 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:

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

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

## Try Blockscout X-Ray GPT

Experience the power of the Blockscout MCP server through our showcase GPT: **[Blockscout X-Ray](https://chatgpt.com/g/g-68a7f315edf481918641bd0ed1e60f8b-blockscout-x-ray)**

This GPT demonstrates the full capabilities of the MCP server, providing intelligent blockchain analysis and insights. It's a great way to explore what's possible when AI agents have contextual access to blockchain data.

### Local Development Setup (For Developers)

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

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

## Technical details

Refer to [SPEC.md](SPEC.md) for the technical details.

## Repository Structure

Refer to [AGENTS.md](AGENTS.md) for the repository structure.

## Testing

Refer to [TESTING.md](TESTING.md) for comprehensive instructions on running both **unit and integration tests**.

## Tool Descriptions

1. `__unlock_blockchain_analysis__()` - Provides custom instructions for the MCP host to use the server. This is a mandatory first step before using other tools.
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