CometBFT validator ops

A read-only MCP server for CometBFT node and validator operators.

Ask your agent "Is my validator signing?", "How close is it to jail?", "Why did the chain stop?" or "Are we ready for the upgrade?" and get an answer grounded in your own nodes and the chain's own slashing state — judged the way an operator would judge them, and unable to change anything.

Works with any CometBFT chain (Cosmos Hub, Osmosis, any Cosmos SDK chain, non-SDK CometBFT apps) and any MCP client (Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, …).

Warning

Early release (v0.4). The tool API may still change.

_{Real tool output against the bundled localnet — nodes are actually stopped; waits are compressed. Reproduce it.}

Contents: What you can ask · Quick start · Install · Connect a client · Configuration · Tools · Security model · How it decides · Troubleshooting · FAQ · Development

What you can ask

Real output from the bundled local network.

Is my validator signing — and how far is it from jail?

"Is val3 signing? How long until it gets jailed?"

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)

Read from commit signatures (works while the validator itself is down) and the chain's own x/slashing counter, with the jail threshold computed exactly as the SDK does.

Why did blocks stop?

"The chain isn't producing blocks. Why?"

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

Tells "not enough voting power online — and who is missing" apart from "validators online but not committing" (an upgrade halt, an app hash error). The 50.1% is not a typo: val2 had been slashed 1% for downtime earlier in the run.

Are we ready for the upgrade?

"Is there an upgrade coming? Are all nodes on the same version?"

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

The x/upgrade plan with an ETA from the measured block time, upgrade proposals still in voting, and version skew across nodes. <untrusted> marks text that came from the chain — here a governance proposal — so the agent treats it as data.

Is everything ok?

"Run a daily check" — or use the daily_check prompt.

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

Also: "Is val0 really behind its sentry?" (peer_health flags validators with public-address peers), "Is any node falling behind?", and incident_triage for an evidence-first diagnosis of one node.

Quick start (1 minute, public RPC)

No access to your nodes needed: point it at a public RPC and watch any validator by its consensus address.

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

Then ask: "Is my-validator signing? How far is it from jail?"

validator_address is the consensus address (…valcons1… or 40-char hex), not a wallet (cosmos1…) or operator (cosmosvaloper1…) address. Get it with <appd> comet show-address on the validator, from /status → validator_info.address, or from an explorer.

Install

Connect a client

Use absolute paths: most clients do not expand ~.

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

Configuration

Where the config comes from, first match wins:

1. --config <path>
2. $COMETBFT_MCP_CONFIG_YAML — the YAML itself, for places that take environment variables but not files (containers, hosted MCP runners). Flow style fits on one line:

   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 — a path
4. ~/.config/cometbft-mcp/config.yaml

Start from the commented 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...

There is deliberately no place for keys, mnemonics or tokens; fields that look like secrets are rejected.

Reaching nodes. Only port 26657 (and optionally 1317 on one node) is used. CometBFT binds RPC to 127.0.0.1 by default, so an SSH tunnel needs no node changes and no open ports: ssh -N -L 36657:127.0.0.1:26657 val-1. Do not open RPC to the internet for this.

cometbft-mcp check prints a node_status report locally, without an MCP client, to verify a config.

Without a usable config the server still starts: its tools stay listed and each call explains what to create (it never echoes the config's contents, which may hold internal addresses). Fix the file and restart the MCP server.

Tools

All tools are read-only (readOnlyHint). Every result has a summary, a level (ok / warn / critical / unknown) and findings with stable codes.

Prompts: daily_check (sweep, drill into what is flagged, report as an operator briefing) and incident_triage (arguments node, optional symptom: evidence-first diagnosis ending with what to check on the host).

Security model

Validator operators should not have to trust an LLM with their infrastructure, so this server is built so that it cannot do damage, rather than promising it won't:

• No keys, ever. No config field can point at priv_validator_key.json, a keyring or a mnemonic; secret-looking fields are rejected by name. Nothing reads the filesystem besides the config.
• Read-only by construction. One HTTP client issues only GETs to a hard-coded allowlist: CometBFT /status, /net_info, /validators, /commit, /consensus_state, /abci_info, /health, and Cosmos SDK slashing, staking, upgrade and gov queries. broadcast_*, unsafe_*, dial_*, check_tx, /dump_consensus_state (it lists peer addresses) and /cosmos/tx/ are denied outright; path parameters are pattern-checked; redirects are never followed; responses are size-capped.
• Network details are masked. Peer IPs appear only as a class (private-ipv4, public-ipv4, …), node IDs are truncated, and errors never carry an address, so a sentry-protected validator's IP does not end up in an LLM provider's logs. --reveal-network turns this off, explicitly.
• Node text is untrusted. Everything a node or REST server controls — monikers, versions, error messages, upgrade plans — is wrapped in <untrusted> tags or must match its expected format, so a hostile peer or public RPC cannot inject instructions into your agent.
• Gentle on nodes. A global concurrency cap and bounded block scans; commits are read from sentries or full nodes first.
• Supply chain. Release archives and images carry build-provenance attestations; CI actions and base images are pinned by digest.

Threat model and reporting: SECURITY.md.

How it decides

Liveness. A CometBFT commit lists every validator in the set at that height, in voting-power order, but absent signatures carry no address. So the tool looks for the validator's address in each commit; when it is not there, it reads the validator set at that height and the signature at the validator's index: absent means missed, no index means not in the set. It scans canonical commits only, up to latest − 1: the commit a node returns for the newest height is its seen commit, holding only the precommits that arrived before +2/3, where a validator behind a sentry routinely looks absent. Canonical commits are also what downtime slashing counts.

Jail risk. With the Cosmos SDK layer it reads the chain's own inputs — x/slashing params and signing info, and x/staking matched by consensus key — and computes the threshold exactly as x/slashing does: window − round_half_even(window × min_signed_per_window), including the grace period before start_height + window. A future jailed_until counts as jailed even if the staking lookup fails, because jailing resets the miss counter and would otherwise look like a clean record.

Halts. CometBFT needs more than 2/3 of voting power to prevote and precommit. consensus_diagnosis reads the current round's votes (CometBFT also lists the next round, still empty, which is skipped), checks each vote against the validator at its position, and sums the power that has voted.

Compatibility

Troubleshooting

FAQ

Can it unjail my validator, restart a node or send a transaction? No, by design. There is no code path that signs or writes; see the security model.

Does it need my validator's RPC? No. A validator can be watched by validator_address alone; its signatures are read from your sentries, full nodes or a public RPC.

What leaves my machine? Tool results go to your MCP client and, through it, to the LLM provider: node names, roles, heights, peer counts, validator addresses. IPs and node IDs are masked. For production nodes, get your organization's approval first.

Does it support gno.land? Not yet: Tendermint2's RPC differs from CometBFT's. For gno.land itself see gnoverse/gno-mcp.

Why no disk or memory checks? On purpose: node_exporter and your existing alerting cover host metrics; cometbft-mcp focuses on judgments that need chain rules.

Development

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

The localnet's genesis is tuned so failures show up in seconds (50-block slashing window, 50% min signed, 60 s jail, 30 s voting). Try it interactively:

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 runs lint and unit tests on every push and pull request (skipped when only docs change); the e2e suite runs daily, on demand, and on pull requests labeled e2e. Contributing: CONTRIBUTING.md. The code map and the invariants that must never break: AGENTS.md.

Roadmap

• ICS consumer chains (slashing and jailing live on the provider)
• secp256k1 consensus keys
• Tendermint2 (gno.land) adapter

License

Apache-2.0