Skip to main content
Glama

vpsdoctor-mcp

Leer en español

An MCP server that lets any MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, and others) check the status of, and carry out safe maintenance on, a self-hosted Linux VPS — over plain SSH, with no proprietary agent installed on the server.

Ask "how's the server doing?" and get back service states, disk and RAM usage, uptime, TLS certificate expiry, and a fail2ban summary. Ask it to restart a service or unban an IP, and it will explain exactly what that means before touching anything.

Why

Most VPS-monitoring MCP servers either want you to install a heavyweight agent, or hand the model unrestricted shell access. This one does neither:

  • Just SSH. No agent, no extra service running on the VPS beyond what you already have.

  • A closed set of vetted scripts, installed once under /opt/vpsdoctor-mcp on the VPS, each one small enough to read in a minute (see scripts/).

  • A dedicated, unprivileged system user on the VPS that can, via a narrow sudoers rule, run only those scripts — nothing else, no full root shell.

  • Destructive actions require explicit confirmation. Restarting a service or unbanning an IP always takes two calls: the first one reports what would happen and does nothing; only a second call with confirm=true actually runs it. This mirrors the human-in-the-loop approach used across VerticeDev's other open-source agents.

  • A restart allowlist enforced twice — once by the Python server, once again by the shell script itself on the VPS — so a bug on either side can't restart something you didn't intend to expose.

Related MCP server: SSH MCP Server

What it exposes

Tool

Read-only?

What it does

vps_status

yes

Services, disk, RAM, uptime, TLS certificate expiry, fail2ban summary, backup age

vps_list_banned_ips

yes

IPs currently banned in a fail2ban jail

vps_restart_service

no

Restart a service from your allowlist (two-step confirm)

vps_unban_ip

no

Unban an IP from a fail2ban jail (two-step confirm)

Setup

1. On the VPS

Copy the scripts/ folder to the VPS and run the installer as root:

scp -r scripts/ youruser@your-vps:/tmp/vpsdoctor-mcp-scripts
ssh youruser@your-vps
cd /tmp/vpsdoctor-mcp-scripts && sudo ./install.sh

This creates a dedicated vpsdoctor-mcp system user, installs the scripts under /opt/vpsdoctor-mcp, writes a sudoers rule scoping that user to exactly those scripts, and generates a dedicated SSH keypair. It prints the next steps, including where to copy the private key.

Edit /opt/vpsdoctor-mcp/allowed_services.conf on the VPS to list the services you actually want restartable (one per line — it ships with nginx and mariadb as examples).

2. Where the server runs

git clone https://github.com/miguelmartt/vpsdoctor-mcp
cd vpsdoctor-mcp
pip install -e .
cp .env.example .env   # then edit it

.env:

VPS_HOST=your-vps-ip-or-hostname
VPS_PORT=22
VPS_USER=vpsdoctor-mcp
VPS_SSH_KEY_PATH=~/.ssh/vpsdoctor-mcp-key
SCRIPTS_DIR=/opt/vpsdoctor-mcp
ALLOWED_SERVICES=nginx,mariadb

3. Point your MCP client at it

Claude Desktop / Claude Code (claude_desktop_config.json or equivalent — see examples/claude_desktop_config.json):

{
  "mcpServers": {
    "vpsdoctor": {
      "command": "vpsdoctor-mcp",
      "env": {
        "VPS_HOST": "your-vps-ip-or-hostname",
        "VPS_USER": "vpsdoctor-mcp",
        "VPS_SSH_KEY_PATH": "/absolute/path/to/vpsdoctor-mcp-key",
        "SCRIPTS_DIR": "/opt/vpsdoctor-mcp",
        "ALLOWED_SERVICES": "nginx,mariadb"
      }
    }
  }
}

Any other MCP client that can launch a stdio server works the same way.

Security notes

  • The private key for the dedicated user should never leave the machine running the server. install.sh restricts it in authorized_keys (no pty, no port/agent/X11 forwarding) and, via sudoers, to running only the scripts in this repo — nothing else, even if that key is ever misused.

  • The server refuses unknown SSH host keys (no trust-on-first-use). If this is the first time connecting to the VPS from wherever the server runs, pin its host key first: ssh-keyscan -H your-vps >> ~/.ssh/known_hosts.

  • Review scripts/ before installing — they're short and meant to be read, not trusted blindly.

  • vps_restart_service and vps_unban_ip validate their input twice (once in Python, once in the shell script) before touching anything, and every executed restart/unban is logged at WARNING level for an audit trail.

  • This project does not collect telemetry and makes no network calls other than the SSH connection you configure.

Extending it

Add a new script under scripts/, add it to the sudoers rule by re-running install.sh, and register a matching @mcp.tool() in src/vpsdoctor_mcp/server.py. Pull requests for additional read-only status checks are especially welcome.

Part of the VerticeDev open-source line

Sibling project: vertice-automations (self-hosted automations as small Python services, including VertiGuard: alerts and a Telegram DevOps bot built on this same VPS-control idea).

License

MIT — see LICENSE.

Available Tools

4 tools
vps_list_banned_ipsA
Read-onlyIdempotent

List IP addresses currently banned by fail2ban in the given jail (default: sshd). Read-only.

Inputs: jail.

vps_restart_serviceA
DestructiveIdempotent

Restart a system service on the VPS (e.g. nginx, mariadb).

Only services listed in the server's ALLOWED_SERVICES configuration can be restarted — anything else is refused before it ever reaches the VPS.

This causes a brief service interruption. Call once with confirm=false (or omitted) to see what would happen; nothing runs until you call again with confirm=true.

Inputs: service (required), confirm.

vps_statusA
Read-onlyIdempotent

Get a snapshot of the VPS: service states, disk, RAM, uptime, TLS certificate expiry, fail2ban summary, and (if configured) the age of the last backup. Safe to call any time — read-only.

Inputs: no named parameters.

vps_unban_ipA
Idempotent

Remove an IP address from a fail2ban jail (default: sshd).

Call once with confirm=false (or omitted) to validate the IP and see what would happen; nothing runs until you call again with confirm=true.

Inputs: ip (required), jail, confirm.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct resource/action: status snapshot, banned IP list, service restart, and IP unban. Even though vps_status includes a fail2ban summary, it does not overlap with the detailed list of banned IPs.

    Naming Consistency4/5

    All tools share the vps_ prefix, and three follow a verb_noun pattern (list_banned_ips, restart_service, unban_ip). vps_status is the only deviation, using a noun instead of a verb_noun structure, but the overall pattern remains clear.

    Tool Count5/5

    Four tools is a well-scoped count for a focused VPS doctor utility. Each tool covers a distinct, necessary operation without unnecessary bloat or feature creep.

    Completeness4/5

    The tool set covers the core VPS doctor workflows: status overview, banned IP inspection, service restart, and IP unban. Minor gaps such as start/stop service or managing fail2ban jails exist, but they are not critical to the server's stated purpose.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP-compatible AI clients to remotely manage a Linux server via SSH, supporting file operations, Docker control, Git pulls, and arbitrary command execution.
      ISC