VPS Guardian MCP server

VPS Guardian MCP

VPS Guardian is a secure Model Context Protocol server for AI agents that work with Linux VPSs. It replaces an unrestricted “run this command and paste the result” loop with named, structured and safety-checked operations.

An agent can inspect a workload, collect bounded diagnostics, preview the impact of a change, and request an exact confirmation for a mutation. The server never exposes a general-purpose shell tool.

Explore the project: capabilities · agent workflows · security model · tool catalogue · release notes

<!-- mcp-name: io.github.murzirius/vps-guardian-mcp -->

Quick start

VPS Guardian has two parts:

• The Python MCP server runs on the VPS.
• The small npm launcher runs on the computer where Codex, Claude, Cursor or another AI client is installed. It opens an SSH stdio connection and never uploads the private key.

What you need

• A Linux VPS reachable via SSH.
• An SSH key for that VPS.
• Python 3.10+ on the VPS and Node.js 16+ on the AI client's computer.
• A verified SSH host key. Password-based SSH is intentionally unsupported by the launcher.

1. Install the server on the VPS

Run once on the VPS. This installs the published, pinned release:

sudo mkdir -p /opt/vps-guardian-mcp
sudo chown "$USER" /opt/vps-guardian-mcp
python3 -m venv /opt/vps-guardian-mcp/.venv
/opt/vps-guardian-mcp/.venv/bin/pip install --upgrade pip
/opt/vps-guardian-mcp/.venv/bin/pip install vps-guardian-mcp==0.22.0

For development from source instead:

git clone --branch v0.22.0 https://github.com/murzirius/VPS-Guardian-MCP.git /opt/vps-guardian-mcp
cd /opt/vps-guardian-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

If the server runs as a non-root user, grant only the required read access. Docker and journal features gracefully report as unavailable when that access is absent.

sudo usermod -aG docker <MCP_USER>
sudo usermod -aG systemd-journal <MCP_USER>

Log out and back in after changing groups.

2. Choose a safety mode

Start with read-only; use controlled once the connection is verified.

3. Connect an AI client over SSH

First verify the VPS fingerprint independently and make a normal SSH connection once. That stores the host key in ~/.ssh/knownhosts (or %USERPROFILE%\.ssh\knownhosts on Windows). The launcher requires host-key verification by default.

Use this configuration for JSON-based MCP clients:

{
  "mcpServers": {
    "vps-guardian": {
      "command": "npx",
      "args": [
        "-y",
        "@murzirius/vps-guardian-mcp@0.22.0",
        "--host", "<VPS_IP_OR_HOSTNAME>",
        "--user", "root",
        "--key", "~/.ssh/id_ed25519",
        "--mode", "controlled"
      ]
    }
  }
}

Shortened. The full README is on GitHub.