Blockscout

npx add-mcp 'https://mcp.blockscout.com/mcp'

Máy chủ MCP Blockscout

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ác 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 giàu 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
• Phân chia 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 hoạt động 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 Phân tích Blockscout 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 hay nhất về bảo mậ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ủ MCP Blockscout 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 các yêu cầu của chúng thông qua cổng Blockscout PRO API đã 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 chóng trước khi thực hiện bất kỳ yêu cầu ngược dòng nào.

Để lấy 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.

Thiết lập Claude (Web, Desktop, Cowork) - Được khuyến nghị

Cách dễ nhất để sử dụng máy chủ MCP Blockscout với Claude là máy chủ lưu trữ chính thức: trải nghiệm cài đặt được quản lý, gốc với cập nhật tự động và không cần tự chạy bất cứ điều gì. Thêm nó như một Trình kết nối tùy chỉnh với khóa PRO của riêng bạn. Claude gửi khóa trên mọi yêu cầu trong tiêu đề x-api-key, mà máy chủ chấp nhận như một bí danh cho tiêu đề Blockscout-MCP-Pro-Api-Key của nó.

1. Mở Claude và đi tới Tùy chỉnh > Trình kết nối. Trên các gói Team và Enterprise, chủ sở hữu tổ chức thực hiện việc này trong Cài đặt tổ chức > Trình kết nối.
2. Nhấp Thêm trình kết nối tùy chỉnh. Đặt tên thành Blockscout và URL thành https://mcp.blockscout.com/mcp, sau đó tiếp tục.
3. Để Xác thực là None (Claude tự phát hiện). Cảnh báo rằng trình kết nối không có thông tin xác thực là điều mong đợi: khóa được cung cấp trong bước tiếp theo.
4. Mở Tiêu đề yêu cầu, chọn x-api-key từ danh sách và dán khóa PRO API của bạn làm giá trị. Chọn chính xác tên này; máy chủ không đọc các tên trông tương tự khác trong danh sách.
5. Nhấp Thêm.

Lưu ý: Phần Tiêu đề yêu cầu đang trong giai đoạn beta và chưa có sẵn cho mọi tổ chức. Nếu hộp thoại của bạn không hiển thị phần này, hãy sử dụng Thư mục Trình kết nối bên dưới.

Lưu ý: Trên các gói Team và Enterprise, khóa được nhập một lần bởi Chủ sở hữu và được chia sẻ cho toàn bộ tổ chức. Cài đặt xác thực không thể được chỉnh sửa sau khi trình kết nối được thêm: để thay đổi khóa, hãy xóa trình kết nối và thêm lại.

Sử dụng Thư mục Trình kết nối Claude

Nếu hộp thoại Trình kết nối tùy chỉnh không có phần Tiêu đề yêu cầu, hãy cài đặt trình kết nối Blockscout từ Thư mục Trình kết nối Anthropic chính thức. Nó kết nối với cùng một máy chủ lưu trữ nhưng sử dụng khóa truy cập dùng chung.

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 trình 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 > Trình kết nối > Duyệt trình kết nối
3. Tìm kiếm "Blockscout"
4. Nhấp "Kết nối" để cài đặt

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 trình kết nối.

Thiết lập Claude Code

Chuyể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 như một 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 Apps:

1. Mở trang ứng dụng Blockscout (hoặc tìm kiếm "Blockscout" trong thư mục ứng dụng ChatGPT Apps).
2. Nhấp "Kết nối" để bậ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 đề với 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à bậ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 — hoặc .cursor/mcp.json ở cấp dự án hoặc ~/.cursor/mcp.json toàn cục — 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 MCP Blockscout: 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 một lần cho 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 các 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ề số dư token ERC20 chi tiết cho một địa chỉ với siêu dữ liệu được làm giàu và dữ liệu thị trường.
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 phạm vi 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 phạm vi 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í đố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à các 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ụ thể của hàm.
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ành riêng cho 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 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 của dự án. Điều này cho phép truy cập tất cả dữ liệu, làm giàu 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 gửi cho máy khách; khi chạy qua Docker, hãy chuyển nó tại thời điểm chạy (ví dụ: -e BLOCKSCOUT_PRO_API_KEY=...) thay vì nướ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 — theo 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). Máy chủ cũng đọc khóa từ tiêu đề x-api-key, cho các máy khách có tên tiêu đề bị giới hạn trong danh sách cố định (ví dụ: Claude Custom Connectors). Tiêu đề được cấu hình sẽ thắng khi cả hai đều có mặt; x-api-key chỉ được tham khảo khi tiêu đề được cấu hình bị thiếu hoặc trống và việc vô hiệu hóa các khóa do máy khách cung cấp cũng vô hiệu hóa nó. Điều này hoạt động tương tự cho cả hai giao thức vận chuyển HTTP — các cuộc gọi công cụ MCP-over-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 khóa được cấu hình của chính nó; nếu cả hai đều không có, 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 cho bất kỳ yêu cầu nào cần PRO API thất bại mà không có 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 bị lỗi); các công cụ không sử dụng PRO API không bị ảnh hưởng. Điều này làm cho việc chạy một máy chủ HTTP dùng chung trở nên khả thi, 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 vào 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 tiền để 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 để vô hiệu hóa 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 một thông báo do người vận hành cấu hình mà máy chủ nối 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ụ mà yêu cầu của chúng không mang khóa PRO API (được định dạng đúng) của chính máy khách. Thông báo này tồn tại để công bố việc máy chủ công khai chính thức chuyển sang yêu cầu khóa do máy khách cung cấp bắt buộc, vì vậy chỉ có bản triển khai chính thức mới được đặt thông báo này. Khi biến này không được đặt hoặc trống (mặc định), tính năng này hoàn toàn bị tắt. Các nhà vận hành cộng đồng và tự lưu trữ nên để trống biến này — đặ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 một thông điệp chuyển đổi không áp dụng cho bản 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 host 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 máy khách HTTP đơ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 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 để kiểm thử và gỡ lỗi cục bộ.

Tạo đường hầm với Ngrok (Chế độ Phát triển):

Python MCP SDK thực thi bảo vệ chống ràng buộc lại DNS, theo mặc định chặn các yêu cầu từ đường hầm ngrok. Để bật tạo đường hầm cho phát triển và kiểm thử:

1. Bắt đầu một đường hầm ngrok đến máy chủ cục bộ của bạn:

   ngrok http 8000
   

2. Cấu hình host và nguồn gốc được phép bằ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, bảo vệ chống ràng buộc lại DNS được tự động xác định bởi host liên kết của máy chủ: bật cho localhost, tắt cho không phải 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:cổng.

Để biết thêm chi tiết về tạo đường hầm ngrok với máy chủ MCP, hãy xem tài liệu OpenAI Apps SDK Examples.

Chế độ HTTP với REST API:

Để bật REST API có phiên bản cùng với điểm cuối 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 Hình Ảnh Docker Cục Bộ

Khởi tạo mô-đun con kỹ năng được đóng gói, nướng siêu dữ liệu commit của nó vào ngữ cảnh xây dựng Docker, sau đó xây dựng hình ả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 hình ả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 vùng chứa 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 để máy chủ có thể truy cập từ bên ngoài vùng chứa.

Với Khóa PRO API Blockscout:

Truyền khóa tại thời điểm chạy bằng -e thay vì nướng nó vào hình ảnh (xem Cung cấp Khóa PRO API 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 đ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 PRO API do máy khách 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. Bật tính năng này có nghĩa là đặt một bí mật ký (ít nhất 32 byte — hãy tạo nó, đừng bịa ra), và nó yêu cầu chế độ HTTP và khóa PRO API phía máy chủ (các lệnh gọi được đo lường được phục vụ thượng nguồn trên 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ó bền vững (một 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 trữ:

# 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 bản 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. Mất ổ đĩa hoặc xoay vòng bí mật sẽ vô hiệu hóa các định danh phiên trực tiếp theo thiết kế; mức độ phơi nhiễm được giới hạn bởi TTL được cấu hình. 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 tất cả các định danh trực tiếp trên mỗi lần khởi động lại ngay cả khi ổ đĩ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. 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 ngân sách 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 đó được dự định. Các núm tùy chọn: BLOCKSCOUT_SESSION_MCP_MAX_CALLS và BLOCKSCOUT_SESSION_REST_MAX_CALLS (trần lệnh gọi trên mỗi bề mặt trên một bộ đếm chia sẻ trên mỗi định danh; cả hai mặc định 5; 0 đóng quyền truy cập được đo lường trên bề mặt đó trong khi vẫn để việc cấp định danh và điều hướng get_chains_list mở), 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 máy chủ/máy khách 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ó máy khách 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 để 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à Đo Lường 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 do cộng đồng chạy của máy chủ 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 của chúng tôi.

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

• Tên của công cụ đang đượ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 một trình 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 PRO API có sẵn để ủy quyền yêu cầu, khi có. Đây chỉ là một 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 và sau đó loại bỏ nó) hoặc bí mật và khóa riêng tư. Đặc biệt, khóa PRO API 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óa không thể được khôi phục.

Cách Từ Chối

Bạn có thể tắt 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 đủ.