Rootpilot SSH Diagnose MCP server

rootpilot-ssh-diagnose

This is the open-source, bring-your-own-LLM taste of RootPilot. The full product adds calibrated diagnosis (89.7% across 29 standard failure scenarios, zero false alarms on healthy hosts), alert-triggered auto-diagnosis, history, and multi-host management → rootpilotx.com · deployment repo: rootpilot-release

An MCP server that lets any MCP client — Claude Desktop, Claude Code, or your own — safely collect read-only diagnostics from your servers over SSH. It gathers evidence from a fixed whitelist of read-only commands; your model does the reasoning. The server never runs anything outside the whitelist, and never makes a change to your hosts.

Why

When a server misbehaves, you end up SSH-ing in and running the same twenty commands — df -h, docker ps, dmesg | grep -i oom, free -m — then eyeballing the output. This server turns that into a conversation: your LLM asks for exactly the evidence it needs, gets structured, secret-redacted output back, and reasons about the root cause. You stay in control; nothing leaves your machine except SSH to your own hosts.

Security model (read this first)

• Read-only whitelist. There are exactly 38 built-in commands (get_whitelist lists them all). There is no tool that runs an arbitrary command — not even with a confirmation prompt. Every command only inspects state.
• The only injectable value is a container name, validated against ^[a-zA-Z0-9_.-]+$ before it is ever placed in a command. web; rm -rf / is rejected, not escaped.
• Secrets are redacted from output before it reaches your model: KEY=value secrets, Bearer/Basic tokens, sk-/ghp_/AKIA… key shapes, PEM private-key blocks, and credentials embedded in URLs. docker inspect env values are scrubbed.
• Per-command timeout (15s) and output truncation guard against hangs and floods.
• Credentials stay local. Host definitions live in a file you control; passwords are never logged.

30-second setup

Add the server to your MCP client. For Claude Desktop (claudedesktopconfig.json):

{
  "mcpServers": {
    "rootpilot-ssh-diagnose": {
      "command": "npx",
      "args": ["-y", "@rootpilot/mcp-ssh-diagnose"],
      "env": {
        "RP_HOSTS": "/Users/me/.rootpilot-mcp/hosts.json"
      }
    }
  }
}

Then create hosts.json (see hosts.example.json):

[
  { "name": "prod-1", "host": "1.2.3.4", "port": 22, "user": "rootpilot",
    "auth": { "type": "key", "keyPath": "~/.ssh/rootpilot_key" } },
  { "name": "prod-2", "host": "10.0.0.5", "user": "ops",
    "auth": { "type": "password", "password": "..." } }
]

Restart your client. Ask it: "Diagnose prod-1" (or run the diagnose-host prompt).

Use a least-privilege account. Create a dedicated read-only SSH user for diagnostics rather than reusing root. The commands only read state, but the account should reflect that.

Tools

Two prompts ship built-in: diagnose-host (evidence-first root-cause walkthrough) and health-check (a light sweep).

Configuration

Shortened. The full README is on GitHub.