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 工具提供標準、網頁友善的介面。完整文件請參閱 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、Desktop、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. 點擊 新增。

注意： 請求標頭 區段目前為測試版，尚未對所有組織開放。若您的對話方塊未顯示此區段，請使用下方的 連接器目錄。

注意： 在 Team 與 Enterprise 方案中，金鑰由擁有者輸入一次，並由整個組織共用。連接器新增後無法編輯驗證設定：若要變更金鑰，請移除連接器並重新新增。

使用 Claude 連接器目錄

若自訂連接器對話方塊沒有 請求標頭 區段，請從官方 Anthropic 連接器目錄 安裝 Blockscout 連接器。它連接到相同的託管伺服器，但使用共用存取金鑰。

安裝

選項 1：直接連結

前往 claude.com/connectors/blockscout，並點擊「已使用於」區段中的連結以安裝 Blockscout 連接器。

選項 2：透過設定

1. 開啟 Claude（Web 或 Desktop 應用程式）
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 將在 Claude Code 中作為 MCP 伺服器使用，讓您能直接從編碼環境存取與分析區塊鏈資料。

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-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 key 需求通知。 BLOCKSCOUT_PRO_API_KEY_REQUIRED_NOTICE 存放運營者設定的通知，伺服器會將其附加為工具回應中 notes 欄位的最後一筆資料，前提是該請求未攜帶用戶端自有的（格式正確的）PRO API key。此通知用於宣告官方公開伺服器轉向強制要求用戶端提供金鑰的遷移，因此僅官方部署應設定此變數。當此變數未設定或為空（預設狀態）時，此功能完全關閉。社群版與自架營運者應將其留空——特別是在 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:*"），或指定精確的 host:port 值。

有關 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 映像檔

初始化隨附的 skill 子模組，將其 commit 中繼資料烘焙進 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）：

若要執行 Docker 容器並啟用 HTTP 模式與連接埠對應：

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 Key：

在執行階段使用 -e 傳入金鑰，而非將其烘焙進映像檔（請參閱 向伺服器提供 PRO API Key）：

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 key 的呼叫者，每個由 __unlock_blockchain_analysis__ 發出的工作階段識別碼可進行的工具呼叫次數。此功能預設關閉。啟用此功能表示需設定簽章密鑰（至少 32 位元組——請產生而非自行編造），且需要 HTTP 模式與伺服器端的 PRO API key（計量的呼叫會以上游金鑰提供服務），以及一個用於工作階段資料庫的持久化磁碟區。請僅產生一次密鑰並持久儲存（使用密鑰管理服務或持久化的環境設定）；每次重新啟動與重新部署都必須傳入相同的已儲存值：

# 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 Server，社群執行的伺服器實例預設會收集匿名使用資料。這有助於我們了解哪些工具最受歡迎，並引導我們的開發方向。

我們收集的內容：

• 被呼叫的工具名稱（例如 get_block_number）。
• 提供給工具的參數（session_id 參數在傳輸前會以佔位符遮罩）。
• 所使用的 Blockscout MCP Server 版本。
• 授權請求時可用的 PRO API key 的單向、不可逆雜湊（SHA-256），若存在時。這僅是衍生的指紋——金鑰本身絕不會被傳輸，且無法從雜湊中還原。

我們不收集的內容：

• 我們不收集任何個人資料、IP 位址（中央伺服器會使用寄件者的 IP 透過 Mixpanel 進行地理定位，然後將其丟棄），或密鑰與私鑰本身。特別是 PRO API key 絕不會被傳輸——僅傳輸上述的單向、不可逆指紋，無法從中還原金鑰。

如何退出

您可以隨時透過設定以下環境變數來停用此功能：

export BLOCKSCOUT_DISABLE_COMMUNITY_TELEMETRY=true

授權

此專案採用 Blockscout Software Licence 授權。完整條款請參閱 LICENSE 檔案。