Blockscout

npx add-mcp 'https://mcp.blockscout.com/mcp'

Blockscout MCP 服务器

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

该服务器封装了 Blockscout API，并通过 MCP 暴露区块链数据——余额、代币、NFT、合约元数据——以便 AI 代理和工具（如 Claude、Cursor 或 IDE）能够上下文感知地访问和分析这些数据。

主要特性：

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

使用代理技能进行增强分析

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

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

配置 MCP 客户端

Blockscout PRO API 密钥

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

要获取密钥，请在 Blockscout 开发者门户 注册（免费层级不需要信用卡）并生成 API 密钥；密钥以 proapi_ 为前缀。然后在配置客户端时提供该密钥，如下面各节所示。

Claude 设置（Web、桌面、Cowork）- 推荐

将 Blockscout MCP 服务器与 Claude 一起使用的最简单方式是官方托管服务器：原生、托管的安装体验，自动更新，无需自己运行任何内容。将其作为自定义连接器添加，并使用您自己的 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. 点击 添加。

注意： 请求头 部分目前处于测试阶段，并非所有组织都可用。如果您的对话框未显示该部分，请使用下面的 连接器目录。

注意： 在 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 密钥头并启用 streamable-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 域名转换为对应的以太坊地址。
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 代理示例提示

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 中导出或放置在项目根目录的 gitignored .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 配置（将其设置为空字符串可完全禁用客户端提供的密钥）。服务器还会从 x-api-key 头读取密钥，适用于头名称被限制为固定列表的客户端（例如 Claude 自定义连接器）。当两者都存在时，配置的头优先；仅在配置的头缺失或为空时才查阅 x-api-key，禁用客户端提供的密钥也会同时禁用它。这对两种 HTTP 传输方式的工作方式相同——基于 MCP 的 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 保存由操作员配置的通知，服务器会将其作为工具响应中 notes 字段的最后一条附加内容，前提是这些请求未携带客户端自己的（格式正确的）PRO API 密钥。该通知用于宣布官方公共服务器迁移到强制要求客户端提供密钥，因此只有官方部署才应设置它。当该变量未设置或为空（默认情况）时，该功能完全关闭。社区和自托管操作员应将其留空——尤其是在 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 隧道的更多详细信息，请参阅 https://github.com/openai/openai-apps-sdk-examples/blob/main/README.md#testing-in-chatgpt。

HTTP 模式与 REST API：

要启用带版本控制的 REST API 以及 MCP 端点，请使用 --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 镜像

初始化捆绑的技能子模块，将其提交元数据烘焙到 Docker 构建上下文中，然后构建镜像：

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

从 GitHub 容器注册表拉取

拉取预构建镜像：

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

HTTP 模式与 REST API：

要启用 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 服务器 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 软件许可证授权。完整条款请参阅 LICENSE 文件。