🚀 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。
🛠️ 工具描述
__get_instructions__()- 为 MCP 主机提供使用服务器的自定义指令。由于到目前为止（在 Claude Desktop 上测试），MCP 服务器初始化响应中的instructions字段未被 MCP 主机使用，因此该工具是必需的。get_chains_list()- 返回所有已知链的列表。get_address_by_ens_name(name)- 将 ENS 域名转换为对应的以太坊地址。lookup_token_by_symbol(chain_id, symbol)- 按符号或名称搜索代币地址，返回多个可能的匹配项。get_contract_abi(chain_id, address)- 检索智能合约的 ABI（应用二进制接口）。get_address_info(chain_id, address)- 获取地址的综合信息，包括余额、ENS 关联、合约状态和代币详情。get_tokens_by_address(chain_id, address, cursor=None)- 返回地址持有的详细 ERC20 代币信息，并附带丰富的元数据和市场数据。get_latest_block(chain_id)- 返回最新索引的块号和时间戳。get_transactions_by_address(chain_id, address, age_from, age_to, methods)- 获取特定时间范围内地址的交易记录，并可选择按方法过滤。get_token_transfers_by_address(chain_id, address, age_from, age_to, token)- 返回特定时间范围内地址的 ERC - 20 代币转账记录。transaction_summary(chain_id, hash)- 使用 Blockscout 交易解释器提供人类可读的交易摘要。nft_tokens_by_address(chain_id, address)- 检索地址持有的 NFT 代币，并按集合分组。get_block_info(chain_id, number_or_hash)- 返回块信息，包括时间戳、使用的 gas、燃烧的费用和交易数量。get_transaction_info(chain_id, hash)- 获取包含解码输入参数和详细代币转账信息的综合交易信息。get_transaction_logs(chain_id, hash)- 返回包含解码事件数据的交易日志。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 服务器，请按以下步骤操作：
- 打开 Claude Desktop 并点击“设置”。
- 导航至“开发者”部分。
- 点击“编辑配置”。
- 打开
claude_desktop_config.json文件并配置服务器：
{
"mcpServers": {
"blockscout": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"ghcr.io/blockscout/mcp-server:latest"
]
}
}
}
- 保存文件并重启 Claude Desktop。
- 与 Claude 聊天时，你现在可以启用 Blockscout MCP 服务器，让 Claude 访问区块链数据。
📄 许可证
本项目主要根据 MIT 许可证的条款进行分发。详情请参阅 LICENSE。