Parallax Protocol

parallax-mcp

一个 Model Context Protocol 服务，为 AI 助手和 Agent 提供对 Parallax 网络的结构化只读访问：来自节点的链数据、来自浏览器的索引数据、来自状态页面的网络健康状况，以及 Parallax 文档和 PIP。

它可通过 stdio 在本地运行（Claude Desktop、Claude Code），也可作为远程 Streamable HTTP 服务运行，且绝不会持有或接受私钥。

一个公共实例运行于 https://mcp.parallaxprotocol.org/mcp，该服务已在 MCP Registry 中列出，名称为 io.github.ParallaxProtocol/parallax-mcp。

• 工具
• 资源和提示词
• 使用方法
• 配置
• 安全模型
• 部署
• 开发

工具

工具按组分类，每组都可以关闭。所有结果均为精简 JSON，LAX 数量采用 {"wei": "...", "lax": "..."} 格式；任何第三方可写入的内容都会包装为 {"untrusted": "..."}（参见安全模型）。

chain：来自节点的 JSON-RPC

工具	返回内容
chain_info	链 ID 检查、客户端、区块头及其时间、同步状态、节点、Gas 价格以及节点的 RPC 命名空间
get_block	按编号、哈希或 latest 获取区块，包含区块时间、补贴以及可选的交易摘要
get_transaction	交易及其解码后的 calldata（来自浏览器的已验证 ABI，或标准代币 ABI）
get_receipt	状态、已用 Gas、费用及解码后的事件日志
get_balance	归档节点上任意区块的余额和 nonce
get_code、get_storage_at、get_proof	字节码、存储槽和 EIP-1186 证明
call_contract	只读 eth_call；根据 ABI、浏览器已验证的 ABI 或 balanceOf(address) returns (uint256) 这类签名对参数进行编码并解码结果
estimate_gas	交易的 Gas 和费用
get_logs	受区块范围和数量限制的事件日志
gas_price	eth_gasPrice，以及 Parallax 的 Bitcoin Core 风格费用估算（适用于 1 到 144 个区块）
audit_token_approvals	检查地址授予且仍有效的所有 ERC-20 额度和 NFT 授权，并根据当前合约状态进行核验，提供风险敞口、风险标记、严重程度及精确的撤销调用
wait_for_new_block	最长等待 10 分钟，直到出现下一个区块；适用于不支持资源订阅的客户端
trace_transaction、trace_call	调用树、前状态和选择器（需要 debug 命名空间）

mining：根据区块头和发行计划推导；每项推导均记录在工具描述中

工具	返回内容
mining_stats	区块时间统计、算力估算、难度及其趋势、预期区块时间、矿工份额，以及状态页面上的数据以供比较
supply_info	已发行供应量（交叉核对节点数据和发行计划）、占 2100 万上限的比例、当前奖励和时代、按目标时间和实际速度计算的下一次减半时间
block_reward	区块补贴和费用，以及区块成熟时间

explorer：来自 Blockscout REST API v2

explorer_address、explorer_token_balances、explorer_transactions、explorer_token、explorer_token_holders、explorer_token_transfers、explorer_contract（接口、元数据和可选的源代码）、explorer_internal_transactions、explorer_search、explorer_stats（包括统计服务的计数器）以及 explorer_charts：来自 Blockscout 统计服务的 21 个时间序列（账户、交易、费用、区块、Gas、合约），支持按日、周、月或年分辨率查询。列表采用不透明的 next_cursor 进行分页。

network：来自状态页面和节点

工具	返回内容
network_health	一份报告：警报、正在发生的事件、挖矿去中心化程度和建议的确认数、节点、传播情况、重组、内存池，以及节点自身的链头、对等节点和同步状态，并附带问题列表
network_nodes	向状态页报告的节点
network_incidents	事件历史记录和已验证节点的正常运行时间
network_propagation	区块传播延迟、过时区块和重组
network_trends	过去 7 天内的算力、难度、区块时间、算力价格、安全预算、节点、延迟、正常运行时间和内存池数据，按 4 小时分段
node_peers	节点的对等节点和地址簿，不显示 IP 地址（需要 admin）

mempool：mempool_status（节点级和全网络级）以及 mempool_transactions（需要 txpool）。

docs：search_docs 根据问题对 Parallax 文档和 PIP 进行排名（BM25，并提高标题和章节标题的权重），返回带链接的摘录；read_doc 返回完整页面或 PIP，较长内容会分段返回。 它们让助手能够自行查询 Parallax 的具体信息，而不是根据 Ethereum 或 Bitcoin 猜测。

tx：默认关闭

工具	返回内容
build_unsigned_tx	一笔未签名的 legacy 或 EIP-2930 交易，已填入 nonce、gas 和 gas price，并提供供外部签名器使用的签名载荷及其哈希
decode_tx	解码任意原始交易或签名载荷，并从签名中恢复发送方
broadcast_signed_tx	提交已签名的交易。仅在使用 --allow-broadcast 时注册

节点支持哪些工具

公共 RPC 端点仅提供 eth、net 和 web3。如果节点未提供相应命名空间，需要更多权限的工具（trace_* 需要 debug，node_peers 需要 admin，mempool_transactions 需要 txpool）将不会启用；chain_info 会列出节点提供的内容。要启用所有工具，请将服务指向你自己的节点：

parallaxd --http --http.addr 127.0.0.1 \
  --http.api eth,net,web3,txpool,debug,admin,xhash --gcmode archive --txlookuplimit 0

向 parallax-mcp 开放这些命名空间是安全的：它只会通过只读方法的允许列表调用它们（参见安全模型）。 不要向其他任何对象开放这些命名空间。历史状态（旧区块的余额、调用和追踪）需要 --gcmode archive。

资源和提示词

资源	内容
parallax://chain/parameters	Chain ID、区块时间、PoW 和 ASERT、奖励计划和上限、coinbase 成熟时间、EVM 级别（Berlin）和交易类型、端点
parallax://glossary	工具中使用的 Parallax 和工作量证明术语
parallax://docs、parallax://docs/{path}	docs.parallaxprotocol.org 的文档
parallax://pips、parallax://pips/pip-000N	PIP-0002 至 PIP-0006
parallax://chain/head	最新区块；可订阅：每有新区块（及重组）时发送 resources/updated 通知
parallax://network/alerts	状态页上的活跃警报；可订阅：警报出现、解除或级别变更时发送通知

订阅适用于 stdio 和 HTTP 传输的会话（不适用于 --http-stateless）。只有在有人订阅或等待时，服务才会每隔 --head-poll-interval（15 s）轮询节点，并在最后一个关注者离开十分钟后停止轮询。不支持订阅的客户端可以改为调用 wait_for_new_block。

文档是嵌入二进制文件的快照，可使用 docs 工具搜索。CI 会在构建镜像时从 parallax-docs 仓库的 main 分支和 PIP 讨论中刷新文档，因此发布的镜像包含最新文档；在本地，make sync-content 会从 ../parallax-docs 执行同样的操作（需要 gh CLI）。

提示词：explain_transaction（哈希）、audit_address（地址）、network_health_report。

使用方法

Claude Code

本地，通过 stdio：

claude mcp add parallax -- /path/to/parallax-mcp
# with the transaction tools, against your own node:
claude mcp add parallax -- /path/to/parallax-mcp --groups chain,mining,explorer,network,mempool,docs,tx --rpc-url http://127.0.0.1:8545

远程，通过 HTTP 使用公共实例：

claude mcp add --transport http parallax https://mcp.parallaxprotocol.org/mcp

Claude Desktop

添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "parallax": {
      "command": "/path/to/parallax-mcp",
      "args": ["--log-level", "warn"]
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "parallax": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/parallaxprotocol/parallax-mcp", "--transport", "stdio"]
    }
  }
}

在 Claude Desktop 中添加远程 HTTP 部署时，将其作为自定义连接器（Settings → Connectors → Add custom connector）添加，并填写其 URL，例如 https://mcp.example.org/mcp。

在 shell 中

bin/mcpcall（make tools）是一个用于试用工具的小型 MCP 客户端：

bin/mcpcall tools
bin/mcpcall call get_block '{"block":"latest"}'
bin/mcpcall call call_contract '{"to":"0xd1060183552A88455f037a58B2aC639C7966a214","function":"symbol() returns (string)"}'
bin/mcpcall read parallax://glossary
bin/mcpcall -http http://127.0.0.1:8080/mcp call network_health
bin/mcpcall call trace_transaction '{"hash":"0x…"}' -- --rpc-url http://127.0.0.1:8545

配置

设置按优先级从高到低依次来自标志、PARALLAX_MCP_* 环境变量和可选的 YAML 文件（--config，参见 config.example.yaml）。parallax-mcp -help 会列出所有设置。

标志	默认值
--transport	stdio	stdio 或 http
--rpc-url	https://rpc.parallaxprotocol.org	节点 JSON-RPC（http/https）
--explorer-url	https://explorer.parallaxprotocol.org	Blockscout
--status-url	https://status.parallaxprotocol.org	状态页面
--chain-id	2110	若连接的链不是该链，服务将拒绝启动
--groups	chain,mining,explorer,network,mempool,docs	添加 tx 以启用交易工具
--allow-broadcast	关闭	注册 broadcast_signed_tx（需要 tx）
--http-addr、--http-path	127.0.0.1:8080、/mcp	HTTP 传输
--http-stateless	关闭	无会话：副本无需粘性负载均衡，但资源订阅不可用
--head-poll-interval	15s	客户端订阅或等待时轮询最新区块的频率
--explorer-stats-url	<explorer-url>/stats-service	Blockscout 统计服务，用于图表和计数器
--rate-limit、--rate-burst	2/秒、20	按客户端地址限制，HTTP 传输
--max-concurrent	64	HTTP 传输中正在处理的请求数
--trusted-proxies	无	允许设置 X-Forwarded-For 的代理
--behind-cloudflare	关闭	对来自 Cloudflare 边缘网段的请求，从 CF-Connecting-IP 获取客户端地址
--metrics-addr	关闭	在单独的监听器上提供 Prometheus /metrics
--max-response-bytes	262144	更大的结果会失败，并提示缩小查询范围
--max-log-range、--max-logs	10000、500	get_logs 限制
--status-cache-ttl	15s	状态页面对每个地址每分钟允许 60 次请求
--expose-peer-addresses	关闭	在 node_peers 中显示对等节点 IP；仅限 stdio

安全模型

不可信数据。 代币名称和符号、合约源代码、事件和回滚字符串、解码后的字符串参数、区块浏览器标签和节点名称都由任何人自行选择，也可能被写成操纵读取它们的模型。这类文本会被剥除控制字符、双向文本字符和零宽字符，限制长度，并封装为 {"untrusted": "..."}；服务端的指令会告知模型仅将其视为数据。

从设计上只读。 发往节点的每个请求在离开进程前都会经过只读 JSON-RPC 方法的允许列表，因此，即使节点完全开放了 personal、admin、miner 和 debug，也无法据此解锁账户、签名、更改对等节点、挖矿、回退区块链或读取其数据库。跟踪调用必须指定内置跟踪器；JavaScript 跟踪器会被拒绝。只有使用 --allow-broadcast 时，才允许通过任一传输方式调用 eth_sendRawTransaction；除非提供该标志，否则 HTTP 传输为只读。

不接触密钥。 服务端会构造未签名交易并解码已签名交易；签名在其他地方进行。对于看起来像私钥的 32 字节输入，服务端会拒绝处理，且不会将其回显。broadcast_signed_tx 会拒绝未签名、未受保护（pre-EIP-155）和链不匹配的交易。

有界查询。 区块范围、页面大小、列表长度、响应大小、后端响应大小以及每次调用的时长都设有上限。每个 HTTP 客户端地址都有令牌桶速率限制，并且在途请求数量也设有上限。

隐私。 HTTP 响应绝不会显示来自 admin_peers 的对等节点 IP 地址和节点 ID；使用 stdio 时，只有指定 --expose-peer-addresses 才会显示。

弹性。 后端请求设有超时，并会退避重试（广播除外）。某个数据源失败时，工具会返回其他数据源提供的内容，并将失败信息放在 "errors" 下。状态页响应会缓存，并在并发调用者之间共享；如果无法访问状态页，则会提供最多十分钟前的副本，并标记为过期。

部署

该镜像以静态二进制文件的形式发布在 distroless 上，运行时使用非 root 用户，通过 HTTP 传输监听 8080，支持 amd64 和 arm64，地址为 ghcr.io/parallaxprotocol/parallax-mcp。

docker run -d -p 8080:8080 \
  -e PARALLAX_MCP_RPC_URL=http://your-node:8545 \
  -e PARALLAX_MCP_TRUSTED_PROXIES=10.0.0.0/8 \
  ghcr.io/parallaxprotocol/parallax-mcp

将其置于 TLS 终止反向代理之后，并将 --trusted-proxies 设置为代理的地址，以便按真实客户端应用速率限制。

在 Cloudflare 后面运行时，还要设置 --behind-cloudflare（PARALLAX_MCP_BEHIND_CLOUDFLARE=true）：此时客户端地址会从 CF-Connecting-IP 中读取，但仅限代理入口来自 Cloudflare 公布的边缘 IP 段的请求，因此直接访问源站的任何人都无法指定自己的地址。对于静默 100 秒的响应，Cloudflare 会主动关闭连接；服务器会在运行中的工具调用流上每隔 25 秒向客户端发送 ping，以保持连接（同时也会提前发送响应标头），并在空闲的通知流上写入注释行。请将 MCP 主机名从 Bot Fight Mode 和其他质询功能中排除（Security → WAF → custom rule：hostname equals your MCP host，action Skip），因为 MCP 客户端无法通过浏览器质询。

Coolify

创建一个 ghcr.io/parallaxprotocol/parallax-mcp:<version> Docker 镜像资源， 设置域名，并将 Ports Exposes 设为 8080，然后添加：

PARALLAX_MCP_TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12
PARALLAX_MCP_BEHIND_CLOUDFLARE=true      # when the domain is proxied by Cloudflare
PARALLAX_MCP_RPC_URL=http://your-node:8545   # optional: a node with more namespaces

要在每次发布时自动更新，请跟踪 latest 标签，并在 Coolify 服务器上的 deploy/ 中安装轮询器：systemd 定时器每 5 分钟运行一次 coolify-autodeploy.sh，比较 GHCR 上镜像的摘要与上次部署的摘要；如果摘要发生变化，则调用 127.0.0.1 上的 Coolify API 重新部署。不会有任何请求从外部发起，因此 Coolify 的 API 可以限制为仅供服务器自身访问。随后，CI 会等待公共服务器报告新版本。

请关闭 Coolify 自带的健康检查（它会在容器中运行 curl，而 distroless 镜像不包含该命令）；镜像的 Docker HEALTHCHECK 会改为运行 parallax-mcp healthcheck。HTTP 会话存储在内存中，因此多个副本需要针对 Mcp-Session-Id 标头进行粘性负载均衡；或者使用 --http-stateless，但这会放弃资源订阅。代理必须允许长时间运行的响应（服务器发送事件和 wait_for_new_block）；上文所述的 keep-alive 会让这些连接保持活动状态。/healthz 会返回 ok；使用 --metrics-addr 时，Prometheus 指标会统计按工具和结果（ok、error、partial）分类的工具调用次数、工具和后端延迟、后端重试和错误，以及受速率限制的请求。日志以结构化 JSON 格式写入 stderr。

开发

make            # lint, unit tests, build
make race       # unit tests with the race detector
make live       # integration tests against the real endpoints
make live-full RPC=http://127.0.0.1:8545   # also the debug, admin and txpool tools
make docker

单元测试通过内存中的 MCP 客户端，针对模拟后端运行（internal/testutil：作为 httptest 服务器运行的 JSON-RPC 节点、区块浏览器和状态页面）。test/integration 中的集成测试仅在设置 PARALLAX_MCP_LIVE=1 时运行，并检查不变量，例如节点的供应量与排放计划相符、其算力估算与状态页面一致，而不是每个区块都会变化的值。

目录结构：

cmd/parallax-mcp      the server
cmd/mcpcall           a command-line MCP client
pkg/server            tool registration: timeouts, logging, metrics, size limits
pkg/backend           node (RPC allowlist), blockscout, status (cache)
pkg/tools/*           the tool groups (live: head and alert subscriptions, wait_for_new_block)
pkg/watch             the head and alert poller behind subscriptions
pkg/resources         resources and the embedded docs and PIPs
pkg/prompts           prompts
pkg/evm               ABI encoding and decoding, RPC types
pkg/lax               units and the emission schedule
pkg/untrusted         sanitizing and wrapping third-party text
pkg/config            settings from flags, the environment and YAML
pkg/metrics, pkg/httpx  Prometheus metrics and the backends' HTTP client
internal/transport    stdio and Streamable HTTP (rate limits, health check)
internal/testutil     fake node, explorer and status page for tests

pkg/ 下的包可供其他 Go 程序导入，例如 Parallax Wallet。它可以通过 server.New 从自己的节点提供这些工具，并与自身的工具组并列提供。

节点后端使用 Parallax 自有的 rpc 包和类型，而非 go-ethereum 的类型，因为 Parallax 标头包含 epochStartTime 字段，而 go-ethereum 的类型会丢弃该字段，从而改变区块哈希。

许可证

GNU 通用公共许可证 v3.0；详见 LICENSE。