vps-ops-mcp

Don't give your AI raw root SSH. A safe, structured MCP server that lets Claude (or any MCP client) inspect and operate your VPS — nginx, PM2, SSL, UFW, fail2ban — through typed, allowlisted tools instead of free-form shell access.

Read-only by default. Mutating actions don't even exist unless you opt in with an environment variable.

You: "Is everything OK on my server? Any cert expiring soon?"

Claude → server_health(myvps)     → load 0.08, disk 61%, RAM fine
       → ssl_status(myvps)        → b2fest.com expires in 71 days ✓
       → security_audit(myvps)    → ufw active, root login disabled ✓

Why not just an SSH MCP server?

Generic SSH MCP servers hand the model a root shell and hope for the best. This server takes the opposite approach:

Related MCP server: ssh-remote-mcp

Quickstart

Requires Node 18+ and a working ssh <your-host> from your terminal (key-based auth).

Claude Code

claude mcp add vps-ops -- npx -y vps-ops-mcp

Claude Desktop / Cursor / any MCP client — add to your MCP config:

{
  "mcpServers": {
    "vps-ops": {
      "command": "npx",
      "args": ["-y", "vps-ops-mcp"]
    }
  }
}

Then just ask: "Check the health of myvps" (any alias from your ~/.ssh/config, or user@host).

Enabling mutations (optional)

By default the server is strictly read-only. To enable the two mutating tools (nginx_check_and_reload, pm2_restart):

{
  "mcpServers": {
    "vps-ops": {
      "command": "npx",
      "args": ["-y", "vps-ops-mcp"],
      "env": { "VPS_OPS_ALLOW_MUTATIONS": "true" }
    }
  }
}

Even then: no free-form commands, nginx -t always runs before a reload, and pm2 restart all is refused.

Tools

🔒 = only registered when VPS_OPS_ALLOW_MUTATIONS=true.

About sudo

Some checks (ufw, fail2ban, sshd -T) need root. The server always uses sudo -n (non-interactive): if passwordless sudo isn't configured for those commands, the check degrades gracefully and tells you, instead of hanging on a password prompt. You choose how much to allow in /etc/sudoers.d/.

Safety model

1. No credential handling. We spawn your system ssh binary. Keys, agents, ProxyJump, known_hosts — all yours, all untouched.

2. Fixed command templates. Remote commands are string constants. There is no run_command tool and there never will be one in read-only mode.

3. Allowlist validation. Every user-supplied value (host, app name, domain, unit) must match a strict regex before it goes anywhere near a command line. No escaping heuristics — invalid input is simply rejected.

4. Bounded output. Every call has a timeout and an output cap, so a runaway tail can't flood your context window.

5. Mutations are opt-in and minimal. Two tools, both narrow, both guarded.

Roadmap

• site_provision — nginx vhost + certbot + PM2 registration in one guarded flow

• Docker container inventory & log tools

• Caddy support

• Multi-server fleet summary (health across all hosts)

• Scheduled-check examples (cron + Claude Code headless)

PRs welcome — especially real-world ops workflows this doesn't cover yet.

License

MIT © Azat Akdağ