Blockscout

Blockscout MCP Server

Giao thức Ngữ cảnh Mô hình (MCP) là một giao thức mở được thiết kế để cho phép các tác nhân AI, IDE và công cụ tự động hóa tiêu thụ, truy vấn và phân tích dữ liệu có cấu trúc thông qua các API nhận biết ngữ cảnh.

Máy chủ này bao bọc các API Blockscout và hiển thị dữ liệu blockchain—số dư, token, NFT, siêu dữ liệu hợp đồng—thông qua MCP để các tác nhân và công cụ AI (như Claude, Cursor hoặc IDE) có thể truy cập và phân tích dữ liệu theo ngữ cảnh.

Các tính năng chính:

• Truy cập dữ liệu blockchain theo ngữ cảnh cho các công cụ AI
• Hỗ trợ đa chuỗi thông qua cấu hình Blockscout PRO API với tính năng làm phong phú siêu dữ liệu Chainscout
• REST API có phiên bản: Cung cấp giao diện chuẩn, thân thiện với web cho tất cả các công cụ MCP. Xem API.md để biết tài liệu đầy đủ.
• Hướng dẫn tùy chỉnh cho máy chủ MCP để sử dụng máy chủ
• Tối ưu hóa ngữ cảnh thông minh để tiết kiệm token LLM trong khi vẫn duy trì khả năng truy cập dữ liệu
• Cắt phản hồi thông minh với kích thước trang có thể cấu hình để ngăn tràn ngữ cảnh
• Phân trang con trỏ không minh bạch sử dụng chuỗi mã hóa Base64URL thay vì các tham số phức tạp
• Tự động cắt ngắn các trường dữ liệu lớn với chỉ báo rõ ràng và hướng dẫn truy cập
• Mô hình ToolResponse chuẩn hóa với phản hồi JSON có cấu trúc và hướng dẫn theo dõi
• Khả năng quan sát nâng cao với thông báo tiến trình MCP và cập nhật định kỳ cho các thao tác chạy lâu

Phân tích nâng cao với Kỹ năng tác nhân

Để phân tích blockchain mạnh mẽ và hiệu quả hơn, hãy cài đặt kỹ năng Blockscout Analysis từ kho lưu trữ agent-skills. Kỹ năng này cung cấp cho các tác nhân AI hướng dẫn có cấu trúc về chiến lược thực thi, xử lý phản hồi, các phương pháp bảo mật tốt nhất và điều phối quy trình làm việc.

Tìm hiểu thêm: Xem README agent-skills để biết đầy đủ khả năng và hướng dẫn cài đặt.

Cấu hình máy khách MCP

Khóa API Blockscout PRO

Việc cấu hình máy chủ Blockscout MCP với tác nhân AI yêu cầu khóa API Blockscout PRO. Hầu hết các công cụ dữ liệu định tuyến yêu cầu của chúng qua cổng API Blockscout PRO đã xác thực, vì vậy nếu không có khóa hợp lệ, các công cụ đó sẽ thất bại nhanh trước khi thực hiện bất kỳ yêu cầu thượng nguồn nào.

Để có được khóa, hãy đăng ký trên Cổng nhà phát triển Blockscout (gói miễn phí không yêu cầu thẻ tín dụng) và tạo khóa API; các khóa có tiền tố proapi_. Sau đó cung cấp khóa khi cấu hình máy khách của bạn, như được hiển thị trong các phần bên dưới.

Sử dụng Thư mục kết nối Claude - Khuyến nghị

Cách dễ nhất để sử dụng máy chủ Blockscout MCP với Claude (Web, Desktop và Code) là thông qua Thư mục kết nối Anthropic chính thức. Điều này cung cấp trải nghiệm cài đặt được quản lý, gốc với cập nhật tự động.

Cài đặt

Tùy chọn 1: Liên kết trực tiếp

Truy cập claude.com/connectors/blockscout và nhấp vào các liên kết trong phần "Được sử dụng trong" để cài đặt bộ kết nối Blockscout.

Tùy chọn 2: Qua Cài đặt

1. Mở Claude (ứng dụng Web hoặc Desktop)
2. Đi tới Cài đặt > Bộ kết nối > Duyệt bộ kết nối
3. Tìm kiếm "Blockscout"
4. Nhấp "Kết nối" để cài đặt

Lưu ý: Bộ kết nối yêu cầu gói Claude trả phí (Pro, Team, Max hoặc Enterprise).

Hạn chế: Do sử dụng khóa truy cập dùng chung, có thể có các hạn chế về quyền truy cập và khả năng của bộ kết nối.

Thiết lập Claude Desktop

Để sử dụng máy chủ Blockscout MCP chính thức với khóa PRO API của riêng bạn trong Claude Desktop, hãy chọn một trong các tùy chọn sau:

Tùy chọn 1: Gói MCP (MCPB) — Khuyến nghị

Phù hợp nhất cho: Cài đặt dễ dàng và cập nhật tự động.

1. Tải xuống blockscout-mcp.mcpb mới nhất từ bản phát hành GitHub.
2. Nhấp đúp vào tệp .mcpb để cài đặt trong Claude Desktop.
3. Cấu hình khóa Blockscout PRO API của bạn khi được nhắc.
4. Tiện ích mở rộng tự động kết nối với dịch vụ Blockscout MCP được lưu trữ.

Tùy chọn 2: Docker Proxy

Lưu ý: Docker là bắt buộc cho thiết lập này.

Phù hợp nhất cho: Người dùng quen thuộc với các công cụ dòng lệnh và cấu hình tùy chỉnh.

1. Mở Claude Desktop và nhấp vào Cài đặt

2. Điều hướng đến phần "Nhà phát triển"

3. Nhấp "Chỉnh sửa cấu hình"

4. Mở tệp claude_desktop_config.json và cấu hình máy chủ:

   {
     "mcpServers": {
       "blockscout": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "sparfenyuk/mcp-proxy:latest",
           "--transport",
           "streamablehttp",
           "--headers",
           "Blockscout-MCP-Pro-Api-Key",
           "proapi_your_key_here",
           "--headers",
           "Blockscout-MCP-Intermediary",
           "ClaudeDesktop",
           "https://mcp.blockscout.com/mcp"
         ]
       }
     }
   }
   

5. Lưu tệp và khởi động lại Claude Desktop

Thiết lập Claude Code

Truyền khóa PRO API của bạn qua tiêu đề Blockscout-MCP-Pro-Api-Key khi thêm máy chủ:

claude mcp add --transport http blockscout https://mcp.blockscout.com/mcp \
  --header "Blockscout-MCP-Pro-Api-Key: proapi_your_key_here"

Sau khi chạy lệnh này, Blockscout sẽ có sẵn dưới dạng máy chủ MCP trong Claude Code, cho phép bạn truy cập và phân tích dữ liệu blockchain trực tiếp từ môi trường mã hóa của mình.

Thiết lập ứng dụng ChatGPT

Cài đặt ứng dụng Blockscout từ chợ ứng dụng ChatGPT:

1. Mở trang ứng dụng Blockscout (hoặc tìm kiếm "Blockscout" trong thư mục ứng dụng ChatGPT).
2. Nhấp "Kết nối" để kích hoạt ứng dụng cho tài khoản ChatGPT của bạn.

Thiết lập ứng dụng Codex

1. Mở Codex và đi tới Cài đặt > Máy chủ MCP > Thêm máy chủ.
2. Đặt Tên thành Blockscout, chọn tab Streamable HTTP và đặt URL thành https://mcp.blockscout.com/mcp.
3. Trong Tiêu đề, thêm tiêu đề có khóa Blockscout-MCP-Pro-Api-Key và giá trị proapi_your_key_here.
4. Lưu và khởi động lại ứng dụng Codex.

Thiết lập Codex CLI

Codex CLI không thể đính kèm tiêu đề tùy chỉnh từ dòng lệnh, vì vậy hãy cấu hình nó trong hai bước:

1. Tạo khung mục nhập máy chủ:

   codex mcp add Blockscout --url https://mcp.blockscout.com/mcp
   

2. Chỉnh sửa ~/.codex/config.toml để thêm tiêu đề khóa PRO API và kích hoạt máy khách MCP streamable-HTTP (bắt buộc để các máy chủ MCP từ xa kết nối). Cấu hình kết quả sẽ trông như thế này:

   [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" }
   

Thiết lập Cursor

Thêm máy chủ vào cấu hình MCP Cursor của bạn — cấp dự án .cursor/mcp.json hoặc toàn cục ~/.cursor/mcp.json — cung cấp khóa PRO API của bạn qua tiêu đề Blockscout-MCP-Pro-Api-Key:

{
  "mcpServers": {
    "blockscout": {
      "url": "https://mcp.blockscout.com/mcp",
      "timeout": 180000,
      "headers": {
        "Blockscout-MCP-Pro-Api-Key": "proapi_your_key_here"
      }
    }
  }
}

Thiết lập phát triển cục bộ (Dành cho nhà phát triển)

Nếu bạn muốn chạy máy chủ cục bộ cho mục đích phát triển:

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

Chi tiết kỹ thuật

Tham khảo SPEC.md để biết chi tiết kỹ thuật.

Cấu trúc kho lưu trữ

Tham khảo AGENTS.md để biết cấu trúc kho lưu trữ.

Kiểm thử

Tham khảo TESTING.md để biết hướng dẫn toàn diện về việc chạy cả kiểm thử đơn vị và tích hợp.

Mô tả công cụ

1. __unlock_blockchain_analysis__() - Khởi tạo phiên Blockscout MCP: trả về dữ liệu tham chiếu máy chủ, con trỏ kỹ năng blockscout-analysis và quy tắc phân giải URI. Gọi nó một lần mỗi phiên, trước bất kỳ công cụ nào khác.
2. get_chains_list(query=None) - Trả về danh sách các chuỗi được hỗ trợ, với bộ lọc tùy chọn theo tên, ID chuỗi, tiền tệ gốc hoặc hệ sinh thái.
3. get_address_by_ens_name(name) - Chuyển đổi tên miền ENS thành địa chỉ Ethereum tương ứng.
4. lookup_token_by_symbol(chain_id, symbol) - Tìm kiếm địa chỉ token theo ký hiệu hoặc tên, trả về nhiều kết quả khớp tiềm năng.
5. get_contract_abi(chain_id, address) - Truy xuất ABI (Giao diện nhị phân ứng dụng) cho hợp đồng thông minh.
6. inspect_contract_code(chain_id, address, file_name=None) - Cho phép lấy các tệp nguồn của hợp đồng đã xác minh.
7. get_address_info(chain_id, address) - Lấy thông tin toàn diện về một địa chỉ bao gồm số dư, liên kết ENS, trạng thái hợp đồng, chi tiết token và thẻ công khai.
8. get_tokens_by_address(chain_id, address, cursor=None) - Trả về chi tiết số token ERC20 nắm giữ cho một địa chỉ với siêu dữ liệu và dữ liệu thị trường được làm phong phú.
9. get_block_number(chain_id, [datetime]) - Truy xuất số khối và dấu thời gian cho một ngày/giờ cụ thể hoặc khối mới nhất.
10. get_transactions_by_address(chain_id, address, age_from, age_to, methods, cursor=None) - Lấy các giao dịch cho một địa chỉ trong một khoảng thời gian cụ thể với bộ lọc phương thức tùy chọn.
11. get_token_transfers_by_address(chain_id, address, age_from, age_to, token, cursor=None) - Trả về các chuyển token ERC-20 cho một địa chỉ trong một khoảng thời gian cụ thể.
12. nft_tokens_by_address(chain_id, address, cursor=None) - Truy xuất các token NFT thuộc sở hữu của một địa chỉ, được nhóm theo bộ sưu tập.
13. get_block_info(chain_id, number_or_hash, include_transactions=False) - Trả về thông tin khối bao gồm dấu thời gian, gas đã sử dụng, phí bị đốt và số lượng giao dịch. Có thể tùy chọn bao gồm danh sách các hàm băm giao dịch.
14. get_transaction_info(chain_id, hash, include_raw_input=False) - Lấy thông tin giao dịch toàn diện với các tham số đầu vào đã giải mã và chuyển token chi tiết.
15. read_contract(chain_id, address, abi, function_name, args='[]', block='latest') - Thực thi một hàm hợp đồng thông minh chỉ đọc và trả về kết quả của nó. Đối số abi là một đối tượng JSON mô tả chữ ký của hàm cụ thể.
16. direct_api_call(chain_id, endpoint_path, query_params=None, cursor=None, method='GET', json_body=None) - Gọi một điểm cuối API Blockscout thô cho dữ liệu nâng cao hoặc dữ liệu cụ thể theo chuỗi. Hỗ trợ yêu cầu GET (mặc định) và POST với nội dung JSON.

Ví dụ về lời nhắc cho tác nhân 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?

Phát triển & Triển khai

Cài đặt cục bộ

Nhân bản kho lưu trữ và cài đặt các phụ thuộc:

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

Để tùy chỉnh phần đầu của tiêu đề User-Agent được sử dụng cho các yêu cầu RPC, hãy đặt biến môi trường BLOCKSCOUT_MCP_USER_AGENT (mặc định là "Blockscout MCP"). Phiên bản máy chủ được thêm vào tự động.

Cung cấp khóa PRO API cho máy chủ

Khi bạn tự chạy máy chủ, hãy cung cấp khóa API Blockscout PRO thông qua biến môi trường BLOCKSCOUT_PRO_API_KEY — được xuất trong shell của bạn hoặc đặt trong tệp .env được gitignore trong thư mục gốc dự án. Điều này cho phép tất cả quyền truy cập dữ liệu, làm phong phú thẻ công khai và đọc hợp đồng. Không bao giờ cam kết khóa hoặc nhúng nó vào tệp nhị phân được phân phối cho máy khách; khi chạy qua Docker, hãy truyền nó tại thời điểm chạy (ví dụ: -e BLOCKSCOUT_PRO_API_KEY=...) thay vì nhúng nó vào hình ảnh.

export BLOCKSCOUT_PRO_API_KEY=proapi_your_key_here

Khóa do máy khách cung cấp (giao thức vận chuyển HTTP). Khi máy chủ chạy ở chế độ HTTP, máy khách có thể cung cấp khóa PRO API của riêng mình trong tiêu đề yêu cầu — mặc định là Blockscout-MCP-Pro-Api-Key, có thể cấu hình qua BLOCKSCOUT_PRO_API_KEY_HEADER (đặt thành chuỗi rỗng để vô hiệu hóa hoàn toàn các khóa do máy khách cung cấp). Điều này hoạt động tương tự cho cả hai giao thức vận chuyển HTTP — các lệnh gọi công cụ MCP qua HTTP và REST API. Khóa do máy khách cung cấp được ưu tiên hơn BLOCKSCOUT_PRO_API_KEY cho yêu cầu đó; nếu máy khách không gửi khóa, máy chủ sẽ quay lại sử dụng khóa đã cấu hình của chính nó; nếu không có khóa nào, yêu cầu sẽ thất bại với lỗi chưa được cấu hình. Khóa máy khách có mặt nhưng sai định dạng sẽ làm thất bại bất kỳ yêu cầu nào cần PRO API mà không có phương án dự phòng (máy chủ không bao giờ âm thầm sử dụng khóa của chính nó thay cho khóa máy khách không hợp lệ); các công cụ không sử dụng PRO API không bị ảnh hưởng. Điều này cho phép chạy một máy chủ HTTP dùng chung nơi mỗi máy khách xác thực bằng khóa của riêng mình.

Cảnh báo tín dụng thấp. Quyền truy cập PRO API được tính theo tín dụng. Khi số dư còn lại do API báo cáo giảm xuống dưới ngưỡng có thể cấu hình, mọi công cụ dữ liệu sẽ thêm ghi chú tư vấn vào phản hồi của nó, nhắc nhở người vận hành nạp thêm để quyền truy cập PRO API luôn sẵn sàng cho việc sử dụng khối lượng lớn liên tục. Ngưỡng được đặt qua BLOCKSCOUT_PRO_API_LOW_CREDITS_THRESHOLD (mặc định 5000 tín dụng; đặt thành 0 để tắt ghi chú). Ghi chú được kích hoạt cho bất kỳ số dư nào dưới ngưỡng, bao gồm cả số dư bằng không và âm.

Thông báo yêu cầu khóa PRO API. BLOCKSCOUT_PRO_API_KEY_REQUIRED_NOTICE chứa thông báo do người vận hành cấu hình mà máy chủ thêm làm mục cuối cùng của trường notes trong các phản hồi công cụ có yêu cầu không mang khóa PRO API (đúng định dạng) của chính máy khách. Nó tồn tại để thông báo việc di chuyển của máy chủ công khai chính thức sang các khóa bắt buộc do máy khách cung cấp, vì vậy chỉ triển khai chính thức mới được kỳ vọng đặt nó. Khi biến không được đặt hoặc trống (mặc định), tính năng này hoàn toàn tắt. Người vận hành cộng đồng và tự lưu trữ nên để trống — đặc biệt trong chế độ stdio, nơi bạn tự cấu hình BLOCKSCOUT_PRO_API_KEY và không có tiêu đề yêu cầu nào có thể mang khóa máy khách, thông báo sẽ chỉ lặp lại thông điệp di chuyển không áp dụng cho triển khai của bạn.

Chạy máy chủ

Máy chủ chạy ở chế độ stdio theo mặc định:

python -m blockscout_mcp_server

Chế độ HTTP (chỉ MCP):

Để chạy máy chủ ở chế độ HTTP Streamable (không trạng thái, phản hồi SSE theo mặc định):

python -m blockscout_mcp_server --http

Bạn cũng có thể chỉ định máy chủ lưu trữ và cổng cho máy chủ HTTP:

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

Chế độ phát triển (Phản hồi JSON thuần): Để phát triển và kiểm thử với các HTTP client đơn giản (curl, Insomnia), bạn có thể bật phản hồi JSON thuần thay vì luồng SSE:

export BLOCKSCOUT_DEV_JSON_RESPONSE=true
python -m blockscout_mcp_server --http

Lưu ý: Điều này sẽ vô hiệu hóa Server-Sent Events (SSE) và thông báo tiến trình. Chỉ sử dụng tính năng này cho việc kiểm thử và gỡ lỗi cục bộ.

Tunneling với Ngrok (Chế độ Phát triển):

Python MCP SDK áp dụng cơ chế bảo vệ chống ràng buộc DNS, theo mặc định sẽ chặn các yêu cầu từ tunnel ngrok. Để bật tunneling cho phát triển và kiểm thử:

1. Khởi động một tunnel ngrok trỏ đến máy chủ cục bộ của bạn:

   ngrok http 8000
   

2. Cấu hình host và origin được phép sử dụng URL ngrok của bạn:

   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
   

Lưu ý: Các cài đặt này chủ yếu dành cho mục đích phát triển. Khi các biến này không được đặt, cơ chế bảo vệ chống ràng buộc DNS sẽ được xác định tự động dựa trên host liên kết của máy chủ: được bật cho localhost, bị vô hiệu hóa cho non-localhost (ví dụ: 0.0.0.0). Nếu tiêu đề Host của bạn bao gồm một cổng không chuẩn, hãy sử dụng hậu tố ký tự đại diện :* (ví dụ: "example.com:*") hoặc chỉ định chính xác giá trị host:port.

Để biết thêm chi tiết về tunneling ngrok với máy chủ MCP, hãy xem https://github.com/openai/openai-apps-sdk-examples/blob/main/README.md#testing-in-chatgpt.

Chế độ HTTP với REST API:

Để bật REST API có phiên bản cùng với endpoint MCP, hãy sử dụng cờ --rest (yêu cầu --http).

python -m blockscout_mcp_server --http --rest

Với host và cổng tùy chỉnh:

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

Tùy chọn CLI:

• --http: Bật chế độ HTTP Streamable.
• --http-host TEXT: Host để liên kết máy chủ HTTP (mặc định: 127.0.0.1).
• --http-port INTEGER: Cổng cho máy chủ HTTP (mặc định: 8000).
• --rest: Bật REST API (yêu cầu --http).

Xây dựng Ảnh Docker Cục bộ

Khởi tạo submodule skill đi kèm, nhúng metadata commit của nó vào ngữ cảnh xây dựng Docker, sau đó xây dựng ảnh:

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

Kéo từ GitHub Container Registry

Kéo ảnh đã được xây dựng sẵn:

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

Chạy với Docker

Chế độ HTTP (chỉ MCP):

Để chạy container Docker ở chế độ HTTP với ánh xạ cổng:

docker run --rm -p 8000:8000 ghcr.io/blockscout/mcp-server:latest python -m blockscout_mcp_server --http --http-host 0.0.0.0

Với cổng tùy chỉnh:

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

Chế độ HTTP với REST API:

Để chạy với REST API được bật:

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

Lưu ý: Khi chạy ở chế độ HTTP với Docker, hãy sử dụng --http-host 0.0.0.0 để liên kết với tất cả các giao diện nhằm máy chủ có thể truy cập từ bên ngoài container.

Với Khóa API PRO của Blockscout:

Truyền khóa tại thời điểm chạy bằng -e thay vì nhúng vào ảnh (xem Cung cấp Khóa API PRO cho Máy chủ):

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

Với tính năng đo lường phiên được bật (tùy chọn):

Đo lường phiên giới hạn số lượng lệnh gọi công cụ mà người gọi không có khóa API PRO do client cung cấp có thể thực hiện cho mỗi định danh phiên do __unlock_blockchain_analysis__ cấp. Tính năng này tắt theo mặc định. Việc bật nó có nghĩa là đặt một bí mật ký (ít nhất 32 byte — hãy tạo nó, đừng tự nghĩ ra), đồng thời yêu cầu chế độ HTTP và khóa API PRO phía máy chủ (các lệnh gọi được đo lường sẽ được phục vụ thông qua khóa đó), cùng với một ổ đĩa bền vững cho cơ sở dữ liệu phiên. Tạo bí mật một lần và lưu trữ nó một cách bền vững (trình quản lý bí mật hoặc cấu hình môi trường bền vững); mỗi lần khởi động lại và triển khai lại phải truyền cùng một giá trị đã lưu:

# 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

Hầu hết các triển khai không cần bất kỳ điều nào trong số này: để BLOCKSCOUT_SESSION_SECRET không được đặt (mặc định) và không cần ổ đĩa. Việc mất ổ đĩa hoặc xoay vòng bí mật sẽ vô hiệu hóa các định danh phiên đang hoạt động theo thiết kế; mức độ phơi nhiễm được giới hạn bởi TTL đã cấu hình. Việc tạo lại bí mật nội tuyến trên mỗi docker run là dạng vô tình của việc xoay vòng đó — nó xóa sạch tất cả các định danh đang hoạt động sau mỗi lần khởi động lại mặc dù ổ đĩa cơ sở dữ liệu vẫn tồn tại, vì vậy không bao giờ nhúng lệnh tạo vào lệnh khởi động. Việc khôi phục một bản sao cũ hơn của cơ sở dữ liệu sẽ hồi sinh các hạn mức mà nó đã ghi lại — sau khi khôi phục lịch sử, hãy xoay vòng bí mật trừ khi điều đó là có chủ đích. Các tùy chọn tùy chỉnh: BLOCKSCOUT_SESSION_MCP_MAX_CALLS và BLOCKSCOUT_SESSION_REST_MAX_CALLS (giới hạn lệnh gọi trên mỗi bề mặt trên một bộ đếm định danh dùng chung; cả hai mặc định là 5; 0 đóng quyền truy cập được đo lường trên bề mặt đó trong khi vẫn để mở việc cấp định danh và điều hướng get_chains_list), BLOCKSCOUT_SESSION_TTL_SECONDS (mặc định 900) và BLOCKSCOUT_SESSION_SWEEP_INTERVAL_SECONDS (tần suất các hàng phiên hết hạn được dọn dẹp; mặc định: một lần cho mỗi TTL).

Chế độ Stdio: Chế độ stdio mặc định được thiết kế để sử dụng với các host/client MCP (như Claude Desktop, Cursor) và không có ý nghĩa khi chạy trực tiếp với Docker mà không có client MCP quản lý giao tiếp.

Kiểm thử với Claude Desktop

Sử dụng gói MCP để kiểm thử máy chủ với Claude Desktop.

1. Xây dựng gói theo hướng dẫn trong mcpb/README.md.
2. Mở Claude Desktop.
3. Nhấp đúp để mở tệp blockscout-mcp-dev.mcpb nhằm tự động cài đặt gói.
4. Cấu hình URL Máy chủ MCP Blockscout khi được nhắc (mặc định: http://127.0.0.1:8000/mcp)

Quyền riêng tư và Dữ liệu từ xa Ẩn danh

Để giúp chúng tôi cải thiện Máy chủ MCP Blockscout, các phiên bản máy chủ do cộng đồng vận hành sẽ thu thập dữ liệu sử dụng ẩn danh theo mặc định. Điều này giúp chúng tôi hiểu công cụ nào phổ biến nhất và định hướng nỗ lực phát triển.

Những gì chúng tôi thu thập:

• Tên của công cụ được gọi (ví dụ: get_block_number).
• Các tham số được cung cấp cho công cụ (tham số session_id được che bằng giá trị giữ chỗ trước khi truyền).
• Phiên bản của Máy chủ MCP Blockscout đang được sử dụng.
• Một hàm băm một chiều, không thể đảo ngược (SHA-256) của khóa API PRO có sẵn để ủy quyền yêu cầu, khi có. Đây chỉ là dấu vân tay dẫn xuất — bản thân khóa không bao giờ được truyền và không thể khôi phục từ hàm băm.

Những gì chúng tôi KHÔNG thu thập:

• Chúng tôi không thu thập bất kỳ dữ liệu cá nhân nào, địa chỉ IP (máy chủ trung tâm sử dụng IP của người gửi để định vị địa lý qua Mixpanel rồi loại bỏ nó) hoặc bí mật và khóa riêng tư. Đặc biệt, khóa API PRO không bao giờ được truyền — chỉ có dấu vân tay một chiều, không thể đảo ngược được mô tả ở trên, từ đó không thể khôi phục khóa.

Cách Từ chối

Bạn có thể vô hiệu hóa tính năng này bất cứ lúc nào bằng cách đặt biến môi trường sau:

export BLOCKSCOUT_DISABLE_COMMUNITY_TELEMETRY=true

Giấy phép

Dự án này được cấp phép theo Giấy phép Phần mềm Blockscout. Xem tệp LICENSE để biết các điều khoản đầy đủ.