MCP Server

🚀 Blockscout MCP Server

模型上下文協議（MCP）是一種開放協議，旨在允許AI代理、集成開發環境（IDE）和自動化工具通過上下文感知的API來消費、查詢和分析結構化數據。

本服務器封裝了Blockscout API，並通過MCP公開區塊鏈數據，如餘額、代幣、非同質化代幣（NFT）和合約元數據等，以便AI代理和工具（如Claude、Cursor或IDE）可以在上下文中訪問和分析這些數據。

主要特性：

• 為AI工具提供上下文感知的區塊鏈數據訪問。
• 通過從Chainscout獲取Blockscout實例URL，支持多鏈。
• 為MCP主機提供使用服務器的自定義指令。
• 支持MCP多步驟工具操作的進度通知，允許客戶端跟蹤執行狀態。
• 增強用戶體驗：應客戶端要求，為長時間運行的API查詢（如獲取大量交易歷史記錄）提供定期進度更新，提高響應能力。

🚀 快速開始

模型上下文協議（MCP）是一種開放協議，允許AI代理、IDE和自動化工具通過上下文感知的API來消費、查詢和分析結構化數據。本服務器封裝了Blockscout API，通過MCP公開區塊鏈數據，方便AI代理和工具訪問和分析。

✨ 主要特性

• AI工具的上下文區塊鏈數據訪問：為AI工具提供上下文感知的區塊鏈數據訪問。
• 多鏈支持：通過從Chainscout獲取Blockscout實例URL，支持多鏈。
• 自定義指令：為MCP主機提供使用服務器的自定義指令。
• 進度通知：支持MCP多步驟工具操作的進度通知，允許客戶端跟蹤執行狀態。
• 增強用戶體驗：應客戶端要求，為長時間運行的API查詢提供定期進度更新，提高響應能力。

📦 安裝指南

本地安裝

克隆倉庫並安裝依賴：

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模式：默認的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訪問區塊鏈數據。

💻 使用示例

基礎用法

以下是使用get_chains_list()工具獲取所有已知鏈列表的示例：

# 假設已經正確初始化了MCP客戶端
from your_mcp_client_module import MCP_Client

client = MCP_Client()
chains_list = client.get_chains_list()
print(chains_list)

高級用法

以下是使用get_transactions_by_address()工具獲取特定地址在特定時間範圍內的交易記錄的示例：

# 假設已經正確初始化了MCP客戶端
from your_mcp_client_module import MCP_Client

client = MCP_Client()
chain_id = 'your_chain_id'
address = 'your_address'
age_from = 'your_start_time'
age_to = 'your_end_time'
methods = ['your_method_1', 'your_method_2']

transactions = client.get_transactions_by_address(chain_id, address, age_from, age_to, methods)
print(transactions)

📚 詳細文檔

工具描述

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) - 返回塊信息，包括時間戳、使用的燃氣、燃燒的費用和交易計數。
14. get_transaction_info(chain_id, hash) - 獲取綜合的交易信息，包括解碼的輸入參數和詳細的代幣轉移信息。
15. get_transaction_logs(chain_id, hash) - 返回帶有解碼事件數據的交易日誌。
16. get_address_logs(chain_id, address, cursor=None) - 獲取特定地址發出的帶有解碼事件數據的日誌。

示例提示（待添加）

佔位符：此部分將添加用於聊天或IDE通過MCP服務器檢索和分析區塊鏈數據的實用提示示例。

🔧 技術細節

技術細節請參考 SPEC.md。

🔧 倉庫結構

倉庫結構請參考 AGENTS.md。

🔧 測試

關於運行單元測試和集成測試的全面說明，請參考 TESTING.md。

📄 許可證

本項目主要根據MIT許可證的條款進行分發。詳情請參閱 LICENSE。