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. 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 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 Code

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

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{

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

</details>

Cursor

~/.cursor/mcp.json:

{

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

</details>

VS Code

.vscode/mcp.json:

{

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

</details>

Codex CLI

~/.codex/config.toml:

[mcp_servers.cometbft]

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

</details>

Gemini CLI

~/.gemini/settings.json:

{

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

</details>

Docker (any client)

{

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

Or skip the mount and pass the config inline: "-e", "COMETBFT_MCP_CONFIG_YAML={nodes: [...]}" before the image name.

Inside a container 127.0.0.1 is the container itself: point the config at host.docker.internal (Docker Desktop) or add --network host (Linux) to reach SSH tunnels on the host.

Configuration

Where the config comes from, first match wins:

1. --config
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"}]}'

1. $COMETBFT_MCP_CONFIG — a path
2. ~/.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 and prompts stay listed, and each call explains what to create, ending with a one-line public Cosmos Hub config to try first (it never echoes the config's contents, which may hold internal addresses). Fix the config and restart the MCP server.

Tools

All tools are read-only (readOnlyHint). Every result