Blockscout

Blockscout MCP 服务

模型上下文协议（MCP）是一种开放协议，旨在让 AI Agent、IDE 和自动化工具通过上下文感知 API 使用、查询和分析结构化数据。

此服务封装了 Blockscout API，并通过 MCP 提供区块链数据（余额、代币、NFT、合约元数据），使 AI Agent 和工具（如 Claude、Cursor 或 IDE）能够结合上下文访问和分析这些数据。

主要功能：

• 为 AI 工具提供上下文相关的区块链数据访问
• 通过 Blockscout PRO API 配置支持多链，并利用 Chainscout 元数据进行丰富
• 版本化 REST API：为所有 MCP 工具提供标准的、适用于 Web 的接口。完整文档请参阅 API.md。
• 为 MCP 宿主提供使用此服务的自定义指令
• 智能优化上下文，在保留数据可访问性的同时节省 LLM 令牌
• 智能切分响应，支持配置页面大小，避免上下文溢出
• 使用 Base64URL 编码字符串进行不透明游标分页，替代复杂参数
• 自动截断大型数据字段，并提供清晰提示和访问指南
• 标准化的 ToolResponse 模型，提供结构化 JSON 响应和后续操作说明
• 通过 MCP 进度通知和长时间运行操作的定期更新，增强可观测性

使用 Agent Skills 增强分析能力

如需更强大、高效的区块链分析，请从 agent-skills 仓库安装 Blockscout Analysis 技能。此技能为 AI Agent 提供结构化指导，涵盖执行策略、响应处理、安全最佳实践和工作流编排。

了解更多：完整功能和安装说明请参阅 agent-skills README。

配置 MCP 客户端

Blockscout PRO API 密钥

使用 AI Agent 配置 Blockscout MCP 服务需要 Blockscout PRO API 密钥。大多数数据工具都会通过经过身份验证的 Blockscout PRO API 网关路由请求，因此如果没有有效密钥，这些工具会在发出任何上游请求前立即失败。

要获取密钥，请在 Blockscout Developer Portal 注册（免费套餐无需信用卡）并生成 API 密钥；密钥以 proapi_ 为前缀。然后按照以下章节所示，在配置客户端时提供该密钥。

Claude 设置（Web、桌面应用、Cowork）— 推荐

使用 Claude 连接 Blockscout MCP 服务，最简单的方式是使用官方托管服务：原生、托管式的安装体验，自动更新，无需自行运行任何内容。将其添加为自定义连接器，并使用你自己的 PRO API 密钥。Claude 会在每次请求中通过 x-api-key 请求头发送密钥，服务端会将其视为 Blockscout-MCP-Pro-Api-Key 请求头的别名并接受。

1. 打开 Claude，然后前往 自定义 > 连接器。在 Team 和 Enterprise 套餐中，组织所有者需要前往 组织设置 > 连接器进行操作。
2. 点击添加自定义连接器。将名称设为 Blockscout，URL 设为 https://mcp.blockscout.com/mcp，然后继续。
3. 将身份验证保留为 None（Claude 会自动检测）。出现连接器没有凭据的警告是正常的：密钥会在下一步提供。
4. 打开请求头，从列表中选择 x-api-key，并将你的 PRO API 密钥粘贴为值。请务必选择这个名称；服务端不会读取列表中其他看起来相似的名称。
5. 点击添加。

注意： 请求头部分目前处于 Beta 阶段，尚未向所有组织开放。如果你的对话框中没有显示该部分，请使用下方的Claude 连接器目录。

注意： 在 Team 和 Enterprise 套餐中，所有者输入一次密钥后，整个组织即可共享。添加连接器后无法编辑身份验证设置；若要更改密钥，请移除连接器并重新添加。

使用 Claude 连接器目录

如果自定义连接器对话框中没有请求头部分，请从官方 Anthropic 连接器目录安装 Blockscout 连接器。它连接到同一个托管服务，但使用共享访问密钥。

安装

选项 1：直接链接

访问 claude.com/connectors/blockscout，然后点击“使用于”部分中的链接以安装 Blockscout 连接器。

选项 2：通过设置

1. 打开 Claude（Web 或桌面应用）。
2. 前往“设置”>“连接器”>“浏览连接器”。
3. 搜索“Blockscout”。
4. 点击“连接”进行安装。

限制： 由于使用共享访问密钥，连接器的访问权限和功能可能受到限制。

Claude Code 设置

添加服务时，通过 Blockscout-MCP-Pro-Api-Key 请求头传入你的 PRO API 密钥：

claude mcp add --transport http blockscout https://mcp.blockscout.com/mcp \
  --header "Blockscout-MCP-Pro-Api-Key: proapi_your_key_here"

运行此命令后，Blockscout 将作为 MCP 服务在 Claude Code 中提供，让你能够直接在编码环境中访问和分析区块链数据。

ChatGPT 应用设置

从 ChatGPT 应用市场安装 Blockscout 应用：

1. 打开 Blockscout 应用页面（或在 ChatGPT 应用目录中搜索“Blockscout”）。
2. 点击“连接”，为你的 ChatGPT 账户启用该应用。

Codex 应用设置

1. 打开 Codex，然后前往设置 > MCP 服务 > 添加服务。
2. 将名称设为 Blockscout，选择 Streamable HTTP 选项卡，并将 URL 设为 https://mcp.blockscout.com/mcp。
3. 在请求头下，添加一个请求头，键为 Blockscout-MCP-Pro-Api-Key，值为 proapi_your_key_here。
4. 保存并重启 Codex 应用。

Codex CLI 设置

Codex CLI 无法通过命令行附加自定义请求头，因此需要分两步进行配置：

1. 创建服务条目：

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

2. 编辑 ~/.codex/config.toml，添加 PRO API 密钥请求头并启用可流式 HTTP MCP 客户端（远程 MCP 服务连接所必需）。最终配置应如下所示：

   [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 设置

将该服务添加到 Cursor MCP 配置中——可以使用项目级 .cursor/mcp.json，也可以使用全局 ~/.cursor/mcp.json——并通过 Blockscout-MCP-Pro-Api-Key 标头提供你的 PRO API 密钥：

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

本地开发设置（面向开发者）

如果你想在本地运行该服务进行开发：

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

技术详情

请参阅 SPEC.md 了解技术详情。

仓库结构

请参阅 AGENTS.md 了解仓库结构。

测试

请参阅 TESTING.md，了解运行单元测试和集成测试的完整说明。

工具说明

1. __unlock_blockchain_analysis__() - 初始化 Blockscout MCP 会话：返回服务参考数据、blockscout-analysis 技能指针和 URI 解析规则。每个会话调用一次，并在调用任何其他工具之前调用。
2. get_chains_list(query=None) - 返回支持的链列表，可按名称、链 ID、原生货币或生态系统筛选。
3. get_address_by_ens_name(name) - 将 ENS 域名转换为对应的 Ethereum 地址。
4. lookup_token_by_symbol(chain_id, symbol) - 按符号或名称搜索代币地址，并返回多个可能的匹配项。
5. get_contract_abi(chain_id, address) - 获取智能合约的 ABI（应用程序二进制接口）。
6. inspect_contract_code(chain_id, address, file_name=None) - 获取已验证合约的源文件。
7. get_address_info(chain_id, address) - 获取地址的全面信息，包括余额、ENS 关联、合约状态、代币详情和公开标签。
8. get_tokens_by_address(chain_id, address, cursor=None) - 返回地址持有的详细 ERC20 代币信息，包含丰富的元数据和市场数据。
9. get_block_number(chain_id, [datetime]) - 获取指定日期/时间对应的区块编号和时间戳，或获取最新区块。
10. get_transactions_by_address(chain_id, address, age_from, age_to, methods, cursor=None) - 获取地址在指定时间范围内的交易，并可选择按方法筛选。
11. get_token_transfers_by_address(chain_id, address, age_from, age_to, token, cursor=None) - 返回地址在指定时间范围内的 ERC-20 代币转账记录。
12. nft_tokens_by_address(chain_id, address, cursor=None) - 获取地址持有的 NFT 代币，并按集合分组。
13. get_block_info(chain_id, number_or_hash, include_transactions=False) - 返回区块信息，包括时间戳、已用 gas、销毁的费用和交易数。也可选择包含交易哈希列表。
14. get_transaction_info(chain_id, hash, include_raw_input=False) - 获取全面的交易信息，包括已解码的输入参数和详细的代币转账记录。
15. read_contract(chain_id, address, abi, function_name, args='[]', block='latest') - 执行只读智能合约函数并返回结果。abi 参数是描述特定函数签名的 JSON 对象。
16. direct_api_call(chain_id, endpoint_path, query_params=None, cursor=None, method='GET', json_body=None) - 调用原始 Blockscout API 端点，以获取高级或特定链的数据。支持 GET（默认）和带 JSON 正文的 POST 请求。

面向 AI Agent 的提示词示例

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?

开发与部署

本地安装

克隆仓库并安装依赖：

git clone https://github.com/blockscout/mcp-server.git
cd mcp-server
uv pip install -e . # or `pip install -e .`

如需自定义 RPC 请求所用 User-Agent 标头的前缀，请设置 BLOCKSCOUT_MCP_USER_AGENT 环境变量（默认值为 "Blockscout MCP"）。服务版本会自动追加。

向服务端提供 PRO API 密钥

自行运行服务端时，请通过 BLOCKSCOUT_PRO_API_KEY 环境变量提供 Blockscout PRO API 密钥——可在 shell 中导出该变量，或将其放入项目根目录下已加入 git 忽略列表的 .env 文件中。这样即可启用所有数据访问、公共标签补充信息和合约读取。切勿提交该密钥，也不要将其嵌入交付给客户端的二进制文件中；通过 Docker 运行时，应在运行时传入密钥（例如 -e BLOCKSCOUT_PRO_API_KEY=...），而不是将其写入镜像。

export BLOCKSCOUT_PRO_API_KEY=proapi_your_key_here

客户端提供的密钥（HTTP 传输）。 服务端以 HTTP 模式运行时，客户端可在请求标头中提供自己的 PRO API 密钥——默认标头为 Blockscout-MCP-Pro-Api-Key，可通过 BLOCKSCOUT_PRO_API_KEY_HEADER 配置（将其设为空字符串即可完全禁用客户端提供密钥的功能）。对于标头名称受固定列表限制的客户端（例如 Claude Custom Connectors），服务端也会从 x-api-key 标头读取密钥。如果两个标头都存在，则优先使用已配置的标头；只有在已配置的标头缺失或为空时，才会读取 x-api-key；禁用客户端提供密钥的功能也会同时禁用该标头。两种 HTTP 传输方式的行为相同——MCP-over-HTTP 工具调用和 REST API 均适用。对于该请求，客户端提供的密钥优先于 BLOCKSCOUT_PRO_API_KEY；如果客户端未发送密钥，服务端则使用自身配置的密钥；如果两者都不存在，请求会因未配置而失败。若客户端提供的密钥存在但格式错误，任何需要 PRO API 的请求都会失败，且不会回退（服务端绝不会悄悄改用自身密钥来替代错误的客户端密钥）；不使用 PRO API 的工具不受影响。这样便可运行共享的 HTTP 服务，由每个客户端使用自己的密钥进行身份验证。

低额度警告。 PRO API 访问按额度计费。当 API 报告的剩余额度低于可配置的阈值时，每个数据工具都会在响应中附加一条提示，提醒运营者充值，以确保 PRO API 访问能够继续支持高频使用。阈值通过 BLOCKSCOUT_PRO_API_LOW_CREDITS_THRESHOLD 设置（默认为 5000 个额度；设为 0 可禁用此提示）。只要额度低于阈值，就会触发提示，包括额度为零或负数的情况。

PRO API 密钥要求通知。 BLOCKSCOUT_PRO_API_KEY_REQUIRED_NOTICE 用于存放由运营者配置的通知。当工具请求未携带客户端自己的（格式正确的）PRO API 密钥时，服务端会将该通知作为工具响应 notes 字段的最后一项追加。此功能用于宣布官方公共服务端将迁移到强制要求客户端提供密钥的模式，因此预计只有官方部署会设置此变量。未设置该变量或将其留空（默认状态）时，此功能将完全关闭。社区运营者和自托管运营者应将其留空——尤其是在 stdio 模式下，你需要自行配置 BLOCKSCOUT_PRO_API_KEY，且请求标头无法携带客户端密钥，此时该通知只会重复一条不适用于你部署方式的迁移消息。

运行服务

服务默认以 stdio 模式运行：

python -m blockscout_mcp_server

HTTP 模式（仅 MCP）：

要以 HTTP Streamable 模式运行服务（无状态，默认使用 SSE 响应）：

python -m blockscout_mcp_server --http

你也可以指定 HTTP 服务的主机和端口：

python -m blockscout_mcp_server --http --http-host 0.0.0.0 --http-port 8080

开发模式（纯 JSON 响应）：

在使用简单的 HTTP 客户端（curl、Insomnia）进行开发和测试时，可以启用纯 JSON 响应，而不是 SSE 流：

export BLOCKSCOUT_DEV_JSON_RESPONSE=true
python -m blockscout_mcp_server --http

注意： 这会禁用服务器发送事件（SSE）和进度通知。仅在本地测试和调试时使用。

通过 Ngrok 建立隧道（开发模式）：

Python MCP SDK 会强制启用 DNS 重绑定保护，默认会阻止来自 ngrok 隧道的请求。要在开发和测试时启用隧道：

1. 建立一条通往本地服务的 ngrok 隧道：

   ngrok http 8000
   

2. 使用 ngrok URL 配置允许的主机和来源：

   export BLOCKSCOUT_MCP_ALLOWED_HOSTS="your-tunnel-id.ngrok-free.app"
   export BLOCKSCOUT_MCP_ALLOWED_ORIGINS="https://your-tunnel-id.ngrok-free.app"
   python -m blockscout_mcp_server --http
   

注意： 这些设置主要用于开发。当未设置这些变量时，DNS 重绑定保护会根据服务的绑定主机自动确定：绑定到 localhost 时启用，绑定到非 localhost（例如 0.0.0.0）时禁用。如果 Host 标头包含非标准端口，请使用 :* 通配符后缀（例如 "example.com:*"），或指定准确的主机:端口值。

有关 MCP 服务使用 ngrok 隧道的更多详情，请参阅 OpenAI Apps SDK Examples 文档。

带 REST API 的 HTTP 模式：

要在 MCP 端点旁启用带版本号的 REST API，请使用 --rest 标志（需要同时使用 --http）。

python -m blockscout_mcp_server --http --rest

使用自定义主机和端口：

python -m blockscout_mcp_server --http --rest --http-host 0.0.0.0 --http-port 8080

CLI 选项：

• --http：启用 HTTP Streamable 模式。
• --http-host TEXT：HTTP 服务绑定的主机（默认值：127.0.0.1）。
• --http-port INTEGER：HTTP 服务的端口（默认值：8000）。
• --rest：启用 REST API（需要同时使用 --http）。

在本地构建 Docker 镜像

初始化随附的 skill 子模块，将其提交元数据写入 Docker 构建上下文，然后构建镜像：

git submodule update --init --recursive agent-skills
python scripts/bake_skill_metadata.py
docker build -t ghcr.io/blockscout/mcp-server:latest .

从 GitHub Container Registry 拉取

拉取预构建的镜像：

docker pull ghcr.io/blockscout/mcp-server:latest

使用 Docker 运行

HTTP 模式（仅 MCP）：

要通过端口映射以 HTTP 模式运行 Docker 容器：

docker run --rm -p 8000:8000 ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --http-host 0.0.0.0

使用自定义端口：

docker run --rm -p 8080:8080 ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --http-host 0.0.0.0 --http-port 8080

启用 REST API 的 HTTP 模式：

要在启用 REST API 的情况下运行：

docker run --rm -p 8000:8000 ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --rest --http-host 0.0.0.0

**注意：**在 Docker 中以 HTTP 模式运行时，使用 --http-host 0.0.0.0 绑定所有接口，以便从容器外部访问服务。

使用 Blockscout PRO API 密钥：

在运行时使用 -e 传入密钥，而不是将其烘焙到镜像中（参见向服务提供 PRO API 密钥）：

docker run --rm -p 8000:8000 -e BLOCKSCOUT_PRO_API_KEY=proapi_your_key_here \
  ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --http-host 0.0.0.0

启用会话计量（可选）：

会话计量会限制未提供客户端 PRO API 密钥的调用方，在每个由 __unlock_blockchain_analysis__ 签发的会话标识符下可调用工具的次数。默认情况下，此功能处于关闭状态。启用时，需要设置签名密钥（至少 32 字节——请生成密钥，不要凭空编造），并且需要使用 HTTP 模式和服务端 PRO API 密钥（计量调用会使用该密钥转发至上游），还需要为会话数据库配置持久化卷。只生成一次密钥并妥善持久保存（使用密钥管理器或持久化环境配置）；每次重启和重新部署都必须传入同一个已存储的值：

# Once, not per start: generate the secret and keep it.
BLOCKSCOUT_SESSION_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

docker run --rm -p 8000:8000 \
  -v blockscout-mcp-sessions:/data \
  -e BLOCKSCOUT_SESSION_SECRET="$BLOCKSCOUT_SESSION_SECRET" \
  -e BLOCKSCOUT_SESSION_DB_PATH=/data/sessions.db \
  -e BLOCKSCOUT_PRO_API_KEY=proapi_your_key_here \
  ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --http-host 0.0.0.0

大多数部署不需要这些设置：保持 BLOCKSCOUT_SESSION_SECRET 未设置（默认值），也不需要卷。丢失卷或轮换密钥会使有效会话标识符失效，这是有意设计的；风险范围受配置的 TTL 限制。每次 docker run 时内联重新生成密钥，就是这种轮换的意外形式——即使数据库卷仍在，每次重启也会清除所有有效标识符，因此切勿将生成命令嵌入启动命令中。恢复较早的数据库副本会重新启用其中记录的额度；执行历史数据恢复后，应轮换密钥，除非这是预期行为。可选设置：BLOCKSCOUT_SESSION_MCP_MAX_CALLS 和 BLOCKSCOUT_SESSION_REST_MAX_CALLS（同一标识符共享计数器时，各接口的调用上限；默认均为 5；设为 0 会关闭该接口的计量访问，但仍允许签发标识符和通过 get_chains_list 导航）、BLOCKSCOUT_SESSION_TTL_SECONDS（默认值为 900），以及 BLOCKSCOUT_SESSION_SWEEP_INTERVAL_SECONDS（清理过期会话行的频率；默认每个 TTL 清理一次）。

**Stdio 模式：**默认的 stdio 模式专为与 MCP 主机/客户端（如 Claude Desktop、Cursor）配合使用而设计。若没有 MCP 客户端管理通信，直接通过 Docker 运行则没有意义。

使用 Claude Desktop 测试

使用 MCP bundle，通过 Claude Desktop 测试服务。

1. 按照 mcpb/README.md 中的说明构建 bundle。
2. 打开 Claude Desktop。
3. 双击打开 blockscout-mcp-dev.mcpb 文件，以自动安装 bundle。
4. 根据提示配置 Blockscout MCP Server URL（默认值：http://127.0.0.1:8000/mcp）

隐私与匿名遥测

为了帮助我们改进 Blockscout MCP 服务，该服务的社区运行实例默认会收集匿名使用数据。这有助于我们了解哪些工具最受欢迎，并为开发工作提供指导。

我们收集的内容：

• 被调用的工具名称（例如，get_block_number）。
• 提供给工具的参数（传输前会将 session_id 参数替换为占位符）。
• 所使用的 Blockscout MCP 服务版本。
• 请求获得授权时所用 PRO API 密钥的单向、不可逆哈希（SHA-256）（若存在）。这只是派生出的指纹——密钥本身绝不会被传输，也无法通过哈希还原。

我们不会收集的内容：

• 我们不会收集任何个人数据、IP 地址（中央服务会使用发送方的 IP 通过 Mixpanel 进行地理定位，随后将其丢弃），也不会收集机密信息和私钥本身。尤其是，PRO API 密钥绝不会被传输——我们只会收集上述单向、不可逆的指纹，无法通过它还原密钥。

如何选择退出

您可以随时通过设置以下环境变量来停用此功能：

export BLOCKSCOUT_DISABLE_COMMUNITY_TELEMETRY=true

许可证

本项目采用 Blockscout Software Licence 许可。完整条款请参阅 LICENSE 文件。