Easton-OU/rootpilot-mcp

> 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** (claude_desktop_config.json):
Then create hosts.json (see hosts.example.json):
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
| tool | arguments | what it does |
|---|---|---|
| list_hosts | probe? | List configured hosts; with probe, also test SSH reachability |
| get_whitelist | — | Return all 38 commands (key, purpose, template) so you and the model can audit exactly what can run |
| collect | host, keys[] (≤8), container? | Run specific whitelisted commands and return redacted, truncated output |
| collect_base | host | Shortcut: the base overview (docker_ps, df, df_inode, free, uptime, dmesg_oom, docker_daemon) |
| container_deep_dive | host, container | Shortcut: docker_logs, docker_inspect (redacted), container_state, docker_stats for one container |