MCP Server

🚀 Blockscout MCP Server

Model Context Protocol (MCP) 是一个开放协议，旨在让 AI 代理、集成开发环境（IDE）和自动化工具通过具备上下文感知能力的 API 来消费、查询和分析结构化数据。

本服务器封装了 Blockscout API，并通过 MCP 公开区块链数据，如余额、代币、非同质化代币（NFT）和合约元数据等，以便 AI 代理和工具（如 Claude、Cursor 或 IDE）能够在上下文中访问和分析这些数据。

✨ 主要特性

• 为 AI 工具提供上下文感知的区块链数据访问能力。
• 通过从 Chainscout 获取 Blockscout 实例 URL，支持多链。
• 为 MCP 主机提供使用服务器的自定义指令。
• 支持 MCP 多步骤工具操作的进度通知，允许客户端跟踪执行状态。
• 增强用户体验：应客户端请求，为长时间运行的 API 查询（如获取大量交易历史记录）提供定期进度更新，提高响应能力。

🔧 技术细节

技术细节请参考 SPEC.md。

📂 仓库结构

仓库结构请参考 AGENTS.md。

🧪 测试

关于运行单元测试和集成测试的详细说明，请参考 TESTING.md。

🛠️ 工具描述

1. __get_instructions__() - 为 MCP 主机提供使用服务器的自定义指令。由于到目前为止（在 Claude Desktop 上测试），MCP 服务器初始化响应中的 instructions 字段未被 MCP 主机使用，因此该工具是必需的。
2. get_chains_list() - 返回所有已知链的列表。
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. get_address_info(chain_id, address) - 获取地址的综合信息，包括余额、ENS 关联、合约状态和代币详情。
7. get_tokens_by_address(chain_id, address, cursor=None) - 返回地址持有的详细 ERC20 代币信息，并附带丰富的元数据和市场数据。
8. get_latest_block(chain_id) - 返回最新索引的块号和时间戳。
9. get_transactions_by_address(chain_id, address, age_from, age_to, methods) - 获取特定时间范围内地址的交易记录，并可选择按方法过滤。
10. get_token_transfers_by_address(chain_id, address, age_from, age_to, token) - 返回特定时间范围内地址的 ERC - 20 代币转账记录。
11. transaction_summary(chain_id, hash) - 使用 Blockscout 交易解释器提供人类可读的交易摘要。
12. nft_tokens_by_address(chain_id, address) - 检索地址持有的 NFT 代币，并按集合分组。
13. get_block_info(chain_id, number_or_hash) - 返回块信息，包括时间戳、使用的 gas、燃烧的费用和交易数量。
14. get_transaction_info(chain_id, hash) - 获取包含解码输入参数和详细代币转账信息的综合交易信息。
15. get_transaction_logs(chain_id, hash) - 返回包含解码事件数据的交易日志。
16. get_address_logs(chain_id, address, cursor=None) - 获取特定地址发出的包含解码事件数据的日志。

📦 安装指南

本地安装

克隆仓库并安装依赖：

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

运行服务器

服务器默认以 stdio 模式运行：

python -m blockscout_mcp_server

HTTP 流式模式： 若要以 HTTP 流式模式（无状态，JSON 响应）运行服务器：

python -m blockscout_mcp_server --http

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

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

CLI 选项：

• --http：启用 HTTP 流式模式。
• --http-host TEXT：HTTP 服务器绑定的主机（默认：127.0.0.1）。
• --http-port INTEGER：HTTP 服务器的端口（默认：8000）。

本地构建 Docker 镜像

使用官方标签构建 Docker 镜像：

docker build -t ghcr.io/blockscout/mcp-server:latest .

从 GitHub 容器注册表拉取镜像

拉取预构建的镜像：

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

使用 Docker 运行

HTTP 流式模式： 若要以 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

⚠️ 重要提示

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

💡 使用建议

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

配置 Claude Desktop

若要在 Claude Desktop 中使用此 MCP 服务器，请按以下步骤操作：

1. 打开 Claude Desktop 并点击“设置”。
2. 导航至“开发者”部分。
3. 点击“编辑配置”。
4. 打开 claude_desktop_config.json 文件并配置服务器：

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

5. 保存文件并重启 Claude Desktop。
6. 与 Claude 聊天时，你现在可以启用 Blockscout MCP 服务器，让 Claude 访问区块链数据。

📄 许可证

本项目主要根据 MIT 许可证的条款进行分发。详情请参阅 LICENSE。