CometBFT validator ops

面向 CometBFT 节点和验证者运营者的只读 MCP 服务。

向你的 Agent 提问：“我的验证者正在签名吗？”、“距离被监禁还有多久？”、“链为什么停止了？” 或 “我们准备好升级了吗？”，即可获得基于你自己的节点和链自身惩罚状态的回答——按照运营者的判断方式进行判断，并且无法更改任何内容。

适用于任何 CometBFT 链（Cosmos Hub、Osmosis、任何 Cosmos SDK 链、非 SDK CometBFT 应用）和任何 MCP 客户端（Claude Code、Claude Desktop、Cursor、VS Code、Codex、Gemini CLI，等等）。

警告

早期版本（v0.4）。工具 API 仍可能发生变化。

_{针对捆绑的本地网运行的真实工具输出——节点确实已停止；等待时间经过压缩。重现此演示。}

目录： 你可以询问什么 · 快速开始 · 安装 · 连接客户端 · 配置 · 工具 · 安全模型 · 判定方式 · 故障排除 · 常见问题 · 开发

你可以询问什么

以下是捆绑的本地网络中的真实输出。

我的验证者正在签名吗？距离被监禁还有多久？

“val3 正在签名吗？距离被监禁还有多久？”

val3 [critical]: signed 26/30 blocks (88–117), missed 4 (13.33%), 4 missed in a row at the head;
21 more misses until downtime jail (~37s at the current rate)

从提交签名和链自身的 x/slashing 计数器读取数据（验证者本身宕机时也能使用），并按照 SDK 的方式精确计算监禁阈值。

区块为什么停止生成？

“链不再生成区块了。为什么？”

height 115 round 0 (Prevote) for 60s [critical]: prevotes 50.1%, precommits 0.0% of power —
no_quorum; not voting: val3, val2

区分*“在线投票权不足——以及缺少哪些验证者”与“验证者在线但未提交”*（升级停机、应用哈希错误）。50.1% 不是笔误：val2 在本次运行中早些时候因停机被罚没了 1%。

我们准备好升级了吗？

“要升级了吗？所有节点都使用相同版本吗？”

localnet-1 [ok]: upgrade <untrusted>v2-e2e</untrusted> at height 10000000 in ~164d20h (9999969 blocks)

x/upgrade 计划及根据实测区块时间估算的预计时间、仍在投票中的升级提案，以及各节点之间的版本差异。<untrusted> 标记来自链上的文本——此处为治理提案——因此 Agent 会将其视为数据。

一切正常吗？

“运行每日检查”——或使用 daily_check 提示词。

[critical] 5 nodes (4 ok, 1 critical), 4 validators (3 ok, 1 critical); localnet-1 [ok]: no upgrade scheduled — needs attention: val3

还可以问：“val0 确实位于其哨兵节点后面吗？”（peer_health 会标记与使用公开地址的节点建立连接的验证者）、“是否有节点正在落后？”，以及使用 incident_triage 对单个节点进行以证据为先的诊断。

快速开始（1 分钟，公共 RPC）

无需访问你的节点：将其指向公共 RPC，即可通过共识地址监控任意验证者。

go install github.com/wookja-0/cometbft-mcp/cmd/cometbft-mcp@latest

cat > hub.yaml <<'EOF'
cosmos:
  rest: https://cosmos-rest.publicnode.com
nodes:
  - name: public
    role: full
    rpc: https://cosmos-rpc.publicnode.com:443
  - name: my-validator
    role: validator
    validator_address: cosmosvalcons1...   # yours, or any validator's
EOF

cometbft-mcp check --config hub.yaml
claude mcp add cometbft -- cometbft-mcp --config "$PWD/hub.yaml" --concurrency 8

然后询问：“我的验证者在签名吗？距离被关进监狱还有多远？”

validator_address 是共识地址（…valcons1… 或 40 位十六进制字符串），不是钱包地址（cosmos1…）或运营者地址（cosmosvaloper1…）。可在验证者上运行 <appd> comet show-address 获取，也可从 /status → validator_info.address 或区块浏览器中获取。

安装

连接客户端

请使用绝对路径：大多数客户端不会展开 ~。

claude mcp add cometbft -- cometbft-mcp --config /Users/you/.config/cometbft-mcp/config.yaml

{
  "mcpServers": {
    "cometbft": {
      "command": "cometbft-mcp",
      "args": ["--config", "/Users/you/.config/cometbft-mcp/config.yaml"]
    }
  }
}

{
  "mcpServers": {
    "cometbft": {
      "command": "cometbft-mcp",
      "args": ["--config", "/Users/you/.config/cometbft-mcp/config.yaml"]
    }
  }
}

{
  "servers": {
    "cometbft": {
      "type": "stdio",
      "command": "cometbft-mcp",
      "args": ["--config", "/Users/you/.config/cometbft-mcp/config.yaml"]
    }
  }
}

[mcp_servers.cometbft]
command = "cometbft-mcp"
args = ["--config", "/Users/you/.config/cometbft-mcp/config.yaml"]

{
  "mcpServers": {
    "cometbft": {
      "command": "cometbft-mcp",
      "args": ["--config", "/Users/you/.config/cometbft-mcp/config.yaml"]
    }
  }
}

{
  "mcpServers": {
    "cometbft": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "--mount", "type=bind,src=/Users/you/.config/cometbft-mcp/config.yaml,dst=/config/config.yaml,readonly",
               "ghcr.io/wookja-0/cometbft-mcp:0.4.2"]
    }
  }
}

配置来源按以下顺序匹配，采用第一个匹配项：

1. --config <path>
2. $COMETBFT_MCP_CONFIG_YAML — YAML 内容本身，适用于支持环境变量但不支持文件的场景（容器、托管 MCP 运行器）。流式风格可以写在一行：

   COMETBFT_MCP_CONFIG_YAML='{cosmos: {rest: "https://cosmos-rest.publicnode.com"}, nodes: [{name: public, role: full, rpc: "https://cosmos-rpc.publicnode.com:443"}]}'
   

3. $COMETBFT_MCP_CONFIG — 路径
4. ~/.config/cometbft-mcp/config.yaml

请从带注释的 config.example.yaml 开始。

# Optional: the Cosmos SDK layer (jail status, slashing margin, upgrades, monikers).
# Chain state is the same on every node: use a sentry's or full node's REST API.
cosmos:
  rest: http://127.0.0.1:1317

nodes:
  - name: sentry-1
    role: sentry                     # validator | sentry | full
    rpc: http://127.0.0.1:26657      # CometBFT RPC
  - name: val-1
    role: validator
    rpc: http://127.0.0.1:36657
    validator_address: cosmosvalcons1...   # keeps validator_health working while it is down
  - name: val-2
    role: validator                  # no rpc: watched by address only
    validator_address: cosmosvalcons1...

配置中刻意不提供密钥、助记词或令牌的位置；任何看起来像机密信息的字段都会被拒绝。

连接节点。 只会使用端口 26657（以及某个节点上可选的 1317 端口）。CometBFT 默认将 RPC 绑定到 127.0.0.1，因此 SSH 隧道无需修改节点设置，也无需开放端口：ssh -N -L 36657:127.0.0.1:26657 val-1。请勿为此将 RPC 暴露到互联网。

cometbft-mcp check 会在本地打印 node_status 报告，无需 MCP 客户端即可验证配置。

即使没有可用的配置，服务仍会启动：其工具仍会列出，并在每次调用时说明需要创建什么（它绝不会回显配置内容，因为其中可能包含内部地址）。修复文件后，重启 MCP 服务。

工具

所有工具均为只读（readOnlyHint）。每个结果都包含 summary、level（ok / warn / critical / unknown）以及带有稳定代码的 findings。

提示词： daily_check（全面检查，深入排查标记的问题，并以运维简报的形式报告）和 incident_triage（参数 node、可选参数 symptom：优先依据证据进行诊断，最后列出需要在主机上检查的内容）。

安全模型

验证者运维人员不应被迫将基础设施交给大模型信任，因此本服务的设计原则是无法造成损害，而不是承诺不会：

• 绝不使用密钥。 没有任何配置字段可以指向 priv_validator_key.json、密钥环或助记词；名称看起来像秘密的字段都会被拒绝。除配置外，不会读取文件系统中的任何内容。
• 从设计上只读。 单个 HTTP 客户端只会向硬编码的允许列表发送 GET 请求：CometBFT 的 /status、/net_info、/validators、/commit、/consensus_state、/abci_info、/health，以及 Cosmos SDK 的 slashing、staking、upgrade 和 gov 查询。broadcast_*、unsafe_*、dial_*、check_tx、/dump_consensus_state（它会列出对等节点地址）和 /cosmos/tx/ 均会被直接拒绝；路径参数会进行模式检查；绝不跟随重定向；响应大小有限制。
• 屏蔽网络详情。 对等节点 IP 只会显示为类别（private-ipv4、public-ipv4 等），节点 ID 会被截断，错误信息绝不包含地址，因此受哨兵保护的验证者 IP 不会出现在大模型提供商的日志中。使用 --reveal-network 可明确关闭此功能。
• 节点文本不可信。 所有由节点或 REST 服务控制的内容——名称、版本、错误消息、升级计划——都会用 <untrusted> 标签包裹，或必须符合预期格式，因此恶意对等节点或公共 RPC 无法向你的 Agent 注入指令。
• 尽量减轻节点负担。 设置全局并发上限并限制区块扫描范围；优先从哨兵或全节点读取提交信息。
• 供应链。 发布压缩包和镜像均附带构建溯源证明；CI 操作和基础镜像均按摘要固定。

威胁模型和报告方式：SECURITY.md。

工作原理

活跃性。 CometBFT 的提交信息会按投票权顺序列出该高度的所有验证者，但缺失的签名不包含地址。因此，工具会在每个提交信息中查找验证者地址；如果找不到，就会读取该高度的验证者集合，并查看该验证者索引处的签名：没有签名表示漏签，没有索引表示不在集合中。它只扫描规范提交，扫描上限为 latest − 1：节点为最新高度返回的提交是其已见提交，只包含 +2/3 之前收到的预提交，因此位于哨兵后方的验证者经常会显示为缺席。停机惩罚的计算也使用规范提交。

监禁风险。 借助 Cosmos SDK 层，它会读取链自身的输入——x/slashing 参数和签名信息，以及按共识密钥匹配的 x/staking 信息——并完全按照 x/slashing 的方式计算阈值：window − round_half_even(window × min_signed_per_window)，其中包括 start_height + window 之前的宽限期。如果 jailed_until 在未来，即使 staking 查询失败，也会视为已被监禁，因为监禁会重置漏签计数器，否则记录看起来会像没有漏签。

停滞。 CometBFT 需要超过 2/3 的投票权才能进行预投票和预提交。consensus_diagnosis 会读取当前轮次的投票（CometBFT 也会列出仍为空的下一轮，该轮会被跳过），检查每张投票是否对应其所在位置的验证者，并统计已投票的投票权。

兼容性

故障排查

常见问题

它能解除验证者的监禁状态、重启节点或发送交易吗？ 不能，这是有意为之。代码中没有签名或写入路径；请参阅安全模型。

它需要我的验证者 RPC 吗？ 不需要。仅凭 validator_address 就能监控验证者；其签名数据会从你的哨兵节点、全节点或公共 RPC 读取。

哪些信息会离开我的机器？ 工具结果会发送给 MCP 客户端，再由客户端发送给大模型提供商：节点名称、角色、高度、对等节点数量、验证者地址。IP 和节点 ID 会被隐藏。对于生产节点，请先获得所在组织的批准。

它支持 gno.land 吗？ 暂不支持：Tendermint2 的 RPC 与 CometBFT 的 RPC 不同。有关 gno.land 本身，请参阅 gnoverse/gno-mcp。

为什么没有磁盘或内存检查？ 这是有意为之：node_exporter 和现有的告警系统会覆盖主机指标；cometbft-mcp 专注于需要链规则才能做出的判断。

开发

make test           # unit tests, no network
make lint
make localnet-up    # 4 validators + 1 sentry (simd) in Docker; writes localnet/config.yaml
make e2e            # MCP over stdio: downtime, a real jail + unjail, an upgrade proposal, a chain halt (~5 min)
go test -tags mainnet -v ./test/mainnet/   # read-only smoke test on Cosmos Hub public endpoints

本地网络的 genesis 经过调整，可让故障在几秒内显现（50 区块惩罚窗口、50% 最低签名率、60 s 监禁时间、30 s 投票时间）。可交互式试用：

make build
claude mcp add cometbft-local -- "$PWD/bin/cometbft-mcp" --config "$PWD/localnet/config.yaml"
make localnet-stop VAL=val3           # "is val3 signing? how long until it's jailed?"
make localnet-stop VAL="val2 val3"    # halt the chain; wait a minute: "why did blocks stop?"
make localnet-down

CI 会在每次推送和拉取请求时运行 lint 和单元测试（仅文档变更时跳过）；端到端测试套件每天运行，也可按需运行，并会在带有 e2e 标签的拉取请求上运行。贡献指南：CONTRIBUTING.md。代码导览以及绝不能破坏的不变量：AGENTS.md。

路线图

• ICS 消费者链（惩罚和监禁状态由提供者链处理）
• secp256k1 共识密钥
• Tendermint2（gno.land）适配器

许可证

Apache-2.0