VPS-Guardian-MCP 🛡️

A secure, open-source Model Context Protocol (MCP) server designed for remote Linux VPS observability, Docker management, configuration editing with automated backups, network security audits, storage diagnostics, scheduled task inspection, OS patch auditing, kernel crash investigations, outbound network latency benchmarks, database health checks, and isolated emergency recovery.

It gives AI agents (Google Antigravity 2.0, Claude Code, Cursor, OpenAI Codex, and Windsurf) named, structured VPS capabilities instead of an unrestricted “run this shell command and paste the output” workflow. The agent calls tools such as get_system_health, inspect_compose_project, or plan_config_deployment; the server validates inputs, limits writable paths, and enforces confirmations for changes.

🚀 Install and Connect an AI Agent

VPS-Guardian has two deliberately separate parts: the Python MCP server runs on the VPS, while a small SSH launcher runs on the computer where Codex, Claude, or another AI client is installed. The launcher never uploads the private key; it only opens the MCP stdio connection through OpenSSH.

Use this section first. It covers installation on the VPS, connection from an AI client, strict SSH host-key verification, and upgrades. The detailed tool catalogue is further down.

What you need

• A Linux VPS reachable via SSH.
• An SSH key that can log in to the VPS. Password-based SSH is intentionally not supported by the npx runner.
• Node.js 16+ on the computer running the AI client; Python 3.10+ on the VPS.
• A trusted VPS: the runner accepts its SSH host key on first connection. Verify the server fingerprint by another channel when that matters for your environment.

1. Install the MCP server on the VPS

Run once on the VPS. /opt/vps-guardian-mcp is the default path used by the client examples.

git clone 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 .

This source-tag route is available now. The project is also prepared for a future PyPI release; after that release, the equivalent production installation will be pipx install vps-guardian-mcp==X.Y.Z on the VPS. Do not use that command until the package is actually published.

If the MCP process will not run as root, grant only the capabilities it needs:

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

Log out and back in after changing group membership. The server still degrades safely when Docker or journal permissions are unavailable.

2. Choose a safety mode

For most users, start with read-only, verify the connection, then choose controlled when you need assisted repairs.

3. Connect from your AI client over SSH

The local launcher keeps MCP's stdio transport clean and opens SSH to the binary installed on the VPS. It now requires an existing verified SSH host key by default. Before adding the MCP, independently verify the VPS fingerprint and establish a normal SSH connection once; OpenSSH will store it in ~/.ssh/known_hosts (or %USERPROFILE%\\.ssh\\known_hosts on Windows).

The version-pinned GitHub route below is available now. A scoped npm launcher is prepared as @murzirius/vps-guardian-mcp; after its first npm release, replace the github:... item with @murzirius/vps-guardian-mcp@X.Y.Z.

{
  "mcpServers": {
    "vps-guardian": {
      "command": "npx",
      "args": [
        "-y",
        "github:murzirius/VPS-Guardian-MCP#v0.18.0",
        "--host", "<VPS_IP_OR_HOSTNAME>",
        "--user", "root",
        "--key", "~/.ssh/id_ed25519",
        "--mode", "controlled"
      ]
    }
  }
}

Every item in args is a separate argument. Do not combine --host with its value or put the full command in one field.

4. OpenAI Codex / ChatGPT Desktop: fill in the form

Open Settings → MCP servers → Add server, then choose STDIO. Enter the following values. The official Codex guidance confirms that a Desktop MCP server is saved and then restarted, and that command, args, env, and cwd are supported for STDIO servers. OpenAI Docs

Arguments, one per row:

-y
github:murzirius/VPS-Guardian-MCP#v0.18.0
--host
<VPS_IP_OR_HOSTNAME>
--user
root
--key
C:\Users\<WindowsUser>\.ssh\id_ed25519
--mode
controlled

Save the server, restart Codex Desktop, and use /mcp to confirm that vps-guardian is connected. Codex Desktop, the Codex CLI, and the IDE extension share the same MCP configuration on a host. OpenAI Docs

If SSH reports Host key verification failed, do not bypass it. Verify the fingerprint with your hosting provider or another trusted channel, then update the known-hosts entry. The launcher supports --known-hosts <path> when a separate known-hosts file is required. --accept-new-host-key exists only for a consciously chosen first-time bootstrap and should not be used for a sensitive production VPS.

5. Other common client situations

Cursor, Windsurf, Antigravity, or another JSON-configured client

Use the JSON from step 3 in that client's MCP server configuration. Keep the arguments as an array of separate strings.

Claude Code

claude mcp add vps-guardian -- npx -y github:murzirius/VPS-Guardian-MCP#v0.18.0 --host <VPS_IP_OR_HOSTNAME> --user root --key ~/.ssh/id_ed25519 --mode controlled

The SSH user is not root

Replace the value after --user, for example --user deploy. Ensure that account can read the required logs and Docker socket when you expect those tools to work. Do not give passwordless sudo merely to make the MCP work; use the minimum permissions needed.

SSH uses a non-standard port

Add two more arguments after the key path:

--port
2222

The private key is elsewhere or has a Windows path

Set the value after --key to its absolute path, for example C:\Users\<WindowsUser>\.ssh\vps_ed25519. The key is read on the AI client's computer, never uploaded to the VPS.

The MCP server is installed outside /opt/vps-guardian-mcp

Add:

--remote-path
/srv/vps-guardian/.venv/bin/vps-guardian-mcp

You prefer direct OpenSSH instead of npx

Use this only when the client can launch ssh directly. It bypasses the convenience runner but exposes the same MCP server:

{
  "mcpServers": {
    "vps-guardian": {
      "command": "ssh",
      "args": [
        "-q",
        "-i", "~/.ssh/id_ed25519",
        "-o", "StrictHostKeyChecking=yes",
        "-o", "ServerAliveInterval=15",
        "-o", "ServerAliveCountMax=4",
        "root@<VPS_IP_OR_HOSTNAME>",
        "env", "VPS_GUARDIAN_MODE=controlled",
        "/opt/vps-guardian-mcp/.venv/bin/vps-guardian-mcp"
      ]
    }
  }
}

6. Verify the connection

Ask the agent: “Check the CPU and RAM load on my server.” A working connection produces a structured response from get_system_health, rather than an SSH command for you to run.

If the server fails to start:

7. Upgrade safely

Update both ends to the same release:

1. On the VPS, fetch the new tag, inspect any local modifications first, then check out the new release and reinstall:

   cd /opt/vps-guardian-mcp
   git status
   git fetch --tags
   git checkout vX.Y.Z
   .venv/bin/pip install -e .
   

2. In the client MCP configuration, replace #v0.18.0 with #vX.Y.Z, save, and restart the client. If you pinned a release, do not use #main unless you intentionally want unreleased changes.

The running agent process is recreated when the MCP client reconnects, so no separate daemon restart is needed for the default SSH setup.

📊 Project Overview & Statistics

✨ Core Features

1. 🖥️ System & Resource Monitoring (src/monitor.py & src/proc_deep.py)

• get_system_health: Collects a comprehensive system snapshot including per-core CPU utilization, RAM and Swap metrics, root filesystem capacity, Disk I/O counters (read/write operations and throughput), Network I/O metrics, and humanized uptime.
• get_top_processes: Identifies top resource-consuming processes ranked by CPU or memory usage, detailing PID, user, memory RSS, status, and command line summaries using two-pass selective inspection.
• get_process_details: Exhaustive runtime profiling of a specific PID including parent/children hierarchy, CPU percentage, user/system times, thread counts, RSS/VMS/shared memory maps, open file descriptor counts (num_fds), open files sample, active network sockets, I/O counters, and sanitized environment variables.
• detect_zombie_processes: Scans the process table for defunct/zombie processes, identifies their non-reaping parent processes (PPID, command line), and provides diagnostic instructions for clearing stalled processes.
• check_system_limits: Audits Linux kernel and system limits: system-wide file descriptors (/proc/sys/fs/file-nr vs fs.file-max) and process NOFILE limits, process/thread capacity (/proc/sys/kernel/pid_max and NPROC), virtual memory parameters (vm.swappiness, vm.vfs_cache_pressure, vm.max_map_count), and socket backlog limits (somaxconn, tcp_max_syn_backlog), flagging warnings when utilization exceeds 80%.
• check_service_status: Queries systemd service state (active, enabled, recent unit logs) for critical services like Nginx, MySQL, PostgreSQL, and UFW.
• get_failed_systemd_units: Performs rapid system audits to discover degraded or failed systemd units (systemctl --failed).
• read_service_logs: Extracts service logs with pure Python-level keyword/regex filtering (grep_filter), eliminating command injection vectors.

2. 🐳 Docker Management & Control (src/docker_manager.py)

• list_docker_containers: Inspects container inventory, reporting status, image tags, port forwards, bind mounts/volumes, health checks, and exit codes.
• get_docker_container_logs: Safely retrieves stdout and stderr streams for any container with bounded line limits.
• get_docker_stats: Streams live resource telemetry (CPU %, memory usage and limits, network RX/TX, block I/O) equivalent to docker stats.
• docker_container_action: Safely executes container lifecycle operations (start, stop, restart, pause, unpause) with input validation (CONTAINER_NAME_REGEX) and configurable shutdown grace timeouts.
• inspect_docker_container: Detailed architectural introspection of any container, returning network addresses, port mappings, mounted volumes/binds, healthcheck history, restart policies, resource limits, and environment variables with automated credential masking.
• clean_docker_garbage: Reclaims disk space by safely pruning dangling images, stopped containers, unused volumes, and orphan networks (prune_type: 'containers', 'images', 'volumes', 'networks', 'all').

3. 🌐 Network Security & Firewall Diagnostics (src/network.py)

• get_open_ports: Discovers all open and listening network ports (TCP and UDP, IPv4 and IPv6) with corresponding bound processes and PIDs.
• get_ufw_status: Audits Uncomplicated Firewall (UFW) active status, default incoming/outgoing policies, and detailed rule configurations.

4. 📁 File & Configuration Management (src/files.py)

• view_file_content: Safely reads configuration files within authorized administrative paths (/etc/nginx/, /etc/mysql/, /etc/postgresql/, /etc/docker/, /etc/caddy/, /var/www/) with context-protective size bounds.
• write_file_content: Atomically updates configuration files via temporary file staging, preserving original permissions and automatically generating timestamped backup copies (.bak.<timestamp>).
• set_web_file_mode: Token-confirmed, intentionally limited 0644 or 0640 permissions for an existing regular static file under /var/www/; it never changes file content or accepts arbitrary chmod modes.
• list_directory: Explores directory structures up to configurable depth limits within permitted paths.

5. 🌍 Web Server & SSL Diagnostics (src/web.py)

• test_nginx_config: Validates Nginx syntax non-disruptively (nginx -t) before reloading configuration files.
• check_http_endpoint: Checks a public URL's response code, TLS, redirects, latency, and optionally a required text fragment without returning page contents.
• check_http_endpoints: Checks up to 20 public endpoints in one compact deployment-health report.
• get_web_deployment_status: Correlates a public HTTPS response with its local Nginx virtual host and matching TLS certificate.
• check_ssl_certificates: Scans Certbot and Let's Encrypt certificates, verifying domain bindings and alerting if renewal is required (<14 days).
• list_virtual_hosts: Parses virtual host declarations from /etc/nginx/sites-enabled/ and conf.d/ (server names, listening ports, SSL, and reverse proxy targets).

Agent Sessions & Live Server Events (src/agent_runtime.py)

• Agent Sessions: Expiring shared task context with bounded, secret-redacted findings, handoffs, outcomes, and short-lived workload locks.
• Live Server Events: A compact timeline joining VPS-Guardian audit events with important journal entries; event watches provide a resumable cursor for a workload.

ChangeSets & Low-Resource Runtime

• ChangeSets: Stage up to three bounded Nginx configuration files, review secret-redacted diffs, confirm once, then validate, reload, health-check, and roll back together on failure.
• get_runtime_budget: Shows the adaptive limits used on constrained hosts; Guardian stays on-demand and never launches background polling workers.

Remote Project Workspace (src/project_workspace.py)

• Project discovery and inspection: Finds bounded Git/application projects, detects stack markers, and shows Git state without exposing arbitrary filesystem paths.
• Source work without a shell: Lets agents search/read redacted code, stage a short-lived patch, review a diff, apply it with a backup and confirmation, then run fixed safe checks.

6. 🔒 Security Auditing & Intrusion Detection (src/security.py)

• check_failed_logins: Analyzes recent failed SSH authentications to surface brute-force attackers and repeat offending IP addresses.
• get_fail2ban_status: Audits Fail2ban service status, active protection jails, and banned IP registries.
• audit_ssh_config: Analyzes /etc/ssh/sshd_config against hardening guidelines (password auth, root login, port configurations) with a security score (0-100).

7. 💾 Storage & Disk Usage Diagnostics (src/storage.py)

• analyze_disk_usage: Recursively audits directories for high disk usage without following symlinks or descending into pseudo-filesystems (/proc, /sys, /dev, /run). Identifies the largest space consumers and files with humanized size formatting.

8. ⏰ Scheduler & Automation Auditing (src/scheduler.py)

• list_cron_jobs: Scans /etc/crontab, modular /etc/cron.d/, standard cron intervals (daily, hourly, weekly, monthly), and user crontabs with human-friendly schedule translations.
• list_systemd_timers: Audits active and pending systemd timers, reporting triggers, countdowns, and target service activations.

9. 🔄 System Updates & Self-Version Verification (src/updates.py)

• check_system_updates: Audits available operating system packages, flags unpatched security CVE updates, and detects kernel reboot requirements (/var/run/reboot-required). Generates prominent alerts for AI agents.
• check_guardian_updates: Verifies local installation against the upstream GitHub repository to alert operators when a newer version or commit is available.

10. 💥 Kernel Diagnostics & OOM Crash Analysis (src/crash.py)

• check_oom_events: Parses kernel logs to surface Out-Of-Memory (OOM) Killer terminations, identifying terminated processes, PIDs, and consumed RSS memory.
• check_kernel_errors: Scans kernel journal for storage I/O errors, filesystem warnings (EXT4/Btrfs), hardware degradation, and application segfaults.

11. 🚀 Outbound Network Connectivity & DNS Benchmarking (src/net_diag.py)

• test_network_connectivity: Performs 100% pure Python socket benchmarking of DNS resolution latency, TCP handshake time, and TLS handshake latency without shell ping.
• check_dns_health: Audits system DNS resolver health, configured nameservers in /etc/resolv.conf, and latency against core public endpoints.

12. 🗄️ Database & Cache Health (src/database.py)

• get_database_health: Non-invasively audits active local database engines: Redis (pure socket PING and RSS memory), PostgreSQL (pg_isready), MySQL/MariaDB (mysqladmin ping), and SQLite database file integrity.

13. 🔧 Emergency Recovery & Backups (src/recover.py)

• execute_recovery: Executes strictly whitelisted administrative recovery operations:
  • restart_service: Restarts target systemd services with strict identifier validation.
  • clean_docker_cache: Performs a deep prune of dangling/unused images, stopped containers, networks, and build caches.
  • clean_system_logs: Vacuums systemd journal logs older than 3 days and prunes rotated log archives in /var/log.
  • kill_process: Terminates stuck runaway processes by PID while enforcing protections for PID 1, init, and core system daemons.
  • vacuum_systemd_journal: Safely prunes systemd journal logs to a target size threshold (e.g. 200M).
  • clean_package_cache: Cleans APT archive cache and purges obsolete packages (apt-get clean && apt-get autoremove).
  • apply_security_updates: Safely applies pending operating system security patches non-interactively.
  • update_guardian: Automatically updates VPS-Guardian-MCP from GitHub and refreshes the virtual environment.
• create_backup: Creates standalone .tar.gz compressed archives of authorized directories inside an isolated backup repository (/var/backups/vps-guardian/).

14. 🛡️ Server-Enforced Safety & Audit (src/safety.py)

• get_safety_status: Reports the active execution mode, confirmation policy, token lifetime, and audit destination.
• get_audit_events: Returns recent redacted JSONL audit events for state-changing operations.
• State-changing tools use short-lived, single-use confirmation tokens bound to their exact parameters.
• The default read-only mode blocks all state changes at the server boundary.

15. 🚨 Unified Incident Triage (src/incident.py)

• generate_incident_report: Aggregates system pressure, failed services, Docker health, OOM events, kernel errors, databases, security posture, and pending updates into one severity-ranked report.

16. 🔁 Transactional Configuration Deployment (src/deploy.py)

• plan_config_deployment: Stages an Nginx config or Caddyfile candidate outside the live path, runs its native validator, produces a bounded unified diff, and issues a short-lived deployment plan.
• deploy_config_change: Atomically writes the validated plan, creates a backup, reloads the matching service, verifies it is active, and restores the prior configuration if reload or health validation fails.
• Plans are bound to the current file hash; a concurrent file change is rejected instead of overwritten.

17. 📸 State Baselines & Drift Detection (src/snapshot.py)

• create_system_snapshot: Saves a baseline of ports, failed units, cron/timers, Docker inventory, and optional configuration hashes without storing config or cron-command content.
• list_system_snapshots: Lists retained baseline metadata.
• compare_system_snapshots: Prioritizes changes between two snapshots: failed units, new exposed ports, scheduled-task drift, Docker changes, and config hash changes.

18. 🧩 Docker Compose Awareness (src/compose.py)

• list_compose_projects and inspect_compose_project: Discover authorized Compose projects and expose safe topology (services, images, ports, dependencies, healthchecks) without environment values.
• compose_project_action: Token-confirmed up, restart, or stop for a project or an explicit subset of services.

19. 🌍 Cross-Distro Capability Adapters (src/platform.py)

• get_platform_capabilities: Detects package manager, firewall, init system, and Compose availability.
• get_package_updates: Read-only update inventory for APT, DNF/YUM, Pacman, and Zypper.
• get_firewall_status: Normalized status for UFW, firewalld, or nftables; guarded service restart now supports systemd, OpenRC, and SysVinit.

20. 🧭 Agent Workload Topology (src/topology.py)

• get_vps_topology: Builds a bounded map of websites, reverse proxies, Compose projects, containers, listening ports, and databases. It excludes configuration contents, environment values, and credentials.
• find_workload and get_workload_health: Find an application by domain, container, service, port, or path fragment, then show its component health, matching SSL state, and host pressure.
• diagnose_workload and prepare_repair_plan: Gather focused, bounded evidence and create a non-executing repair plan using the existing guarded actions.
• get_change_impact: Shows affected components before a proposed restart, stop, configuration deployment, or update; it never performs that action.
• create_workload_baseline and compare_workload_baseline: Save and compare secret-free known-good state for a single workload.

🤖 Guidelines for AI Agents

When interacting with a host via VPS-Guardian-MCP, AI agents must adhere to the following operational standards:

1. Invoke Native MCP Tools Exclusively: Never simulate or guess server states. Always call the corresponding tool (get_system_health, test_nginx_config, check_oom_events, etc.) to obtain verified ground-truth telemetry.
2. Follow the Principle of Least Privilege: Use read-only diagnostic tools first before suggesting or applying changes.
3. Diagnose Mysterious Crashes Methodically: When an application or container terminates without obvious error logs, always run check_oom_events and check_kernel_errors to identify memory exhaustion or segfaults before restarting.
4. Deploy Web Configurations Transactionally: For supported Nginx configs and Caddyfiles, use plan_config_deployment first, then deploy_config_change; it validates, backs up, reloads, checks service health, and rolls back automatically on failure.
5. Establish and Review Baselines: Create a snapshot after a known-good deployment, then compare it before remediation. Treat critical or warning drift as evidence to investigate, not authorization to change a host.
6. Inspect Compose Before Acting: Inspect a Compose project and limit compose_project_action to only the services that need intervention.
7. Find Before Diagnosing: For an application request, start with get_vps_topology or find_workload, then use get_workload_health and diagnose_workload rather than guessing its container or service name.
8. Plan Before Repairing: Use get_change_impact and prepare_repair_plan as evidence. Neither authorizes a change or bypasses the server-side safety gate.
9. Handle Errors Structurally: Diagnostic outputs and system exceptions are returned as structured JSON payloads. Check the status field ("ok", "error", "unavailable", "forbidden") to decide subsequent actions.
10. Promptly Surface Critical Alerts: When check_system_updates or vps://system-overview flags pending security patches or reboot requirements, prioritize alerting the operator and proposing remediation.
11. Use Server-Issued Confirmation Tokens: In controlled mode, call a state-changing tool once without a token, show its impact plan to the operator, then repeat the exact call with the returned confirmation_token.

📁 Repository Structure

VPS-Guardian-MCP/
├── src/
│   ├── __init__.py          # Package version (v0.19.1)
│   ├── server.py            # FastMCP server, resources, prompts, and tool registry (51 tools)
│   ├── safety.py            # Confirmation tokens, execution modes, and audit log
│   ├── incident.py          # Unified severity-ranked incident report
│   ├── deploy.py            # Validated config deployment, reload health check, and rollback
│   ├── snapshot.py          # Privacy-preserving state baseline and drift comparison
│   ├── compose.py           # Guarded Compose project discovery and lifecycle actions
│   ├── platform.py          # Cross-distro package, firewall, and service capability adapters
│   ├── topology.py          # Workload discovery, diagnosis, impact, and baselines
│   ├── monitor.py           # CPU, RAM, Disk I/O, Network, Services, Logs
│   ├── docker_manager.py    # Container inventory, logs, and live telemetry
│   ├── network.py           # Listening ports, bound processes, and UFW rules
│   ├── files.py             # Whitelisted config viewer, atomic writer, directory inspector
│   ├── web.py               # Nginx syntax verification, SSL checks, virtual host listing
│   ├── security.py          # Failed logins, Fail2ban status, SSH configuration audit
│   ├── storage.py           # Disk usage analyzer and space hog finder
│   ├── scheduler.py         # Cron schedules and systemd timers inspection
│   ├── updates.py           # OS security patch auditor and guardian self-version checker
│   ├── crash.py             # OOM-killer events and kernel error diagnostics
│   ├── net_diag.py          # Outbound network benchmarks and DNS latency checks
│   ├── database.py          # Redis, PostgreSQL, MySQL, and SQLite health audits
│   └── recover.py           # Service restarts, cache/log pruners, process killer, tar.gz backups
├── pyproject.toml           # Package configuration and dependencies
├── LICENSE                  # MIT License (2026, murzirius)
├── .gitignore               # Ignored environments, builds, and caches
├── UPDATES.md               # Project changelog and release history
└── README.md                # Documentation and technical reference

🔧 Direct OpenSSH Appendix

The launcher configuration above is the recommended, version-pinned route. Use these examples only when a client cannot run the local npx wrapper. All examples require a previously verified host key (StrictHostKeyChecking=yes); make a normal verified SSH connection first, or provide a separate trusted known-hosts file with -o UserKnownHostsFile=<path>. Add env VPS_GUARDIAN_MODE=controlled before the remote binary when you need controlled changes; otherwise the server starts in read-only mode.

1. 🚀 Google Antigravity 2.0 / Antigravity IDE

Add to your global or workspace configuration in ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "vps-guardian": {
      "command": "ssh",
      "args": [
        "-q",
        "-i", "C:/Users/<Username>/.ssh/id_ed25519",
        "-o", "LogLevel=ERROR",
        "-o", "StrictHostKeyChecking=yes",
        "-o", "ServerAliveInterval=15",
        "-o", "ServerAliveCountMax=4",
        "-o", "TCPKeepAlive=yes",
        "-o", "ConnectTimeout=10",
        "root@<YOUR_VPS_IP>",
        "/opt/vps-guardian-mcp/.venv/bin/vps-guardian-mcp"
      ]
    }
  }
}

2. ⚡ Anthropic Claude Code (CLI Agent)

Add the server with a single terminal command:

claude mcp add vps-guardian -- ssh -q -i ~/.ssh/id_ed25519 -o LogLevel=ERROR -o StrictHostKeyChecking=yes -o ServerAliveInterval=15 -o ServerAliveCountMax=4 -o TCPKeepAlive=yes root@<YOUR_VPS_IP> /opt/vps-guardian-mcp/.venv/bin/vps-guardian-mcp

3. 💻 Cursor IDE

Add to your project or user configuration in .cursor/mcp.json:

{
  "mcpServers": {
    "vps-guardian": {
      "command": "ssh",
      "args": [
        "-q",
        "-i", "~/.ssh/id_ed25519",
        "-o", "LogLevel=ERROR",
        "-o", "StrictHostKeyChecking=yes",
        "-o", "ServerAliveInterval=15",
        "-o", "ServerAliveCountMax=4",
        "-o", "TCPKeepAlive=yes",
        "root@<YOUR_VPS_IP>",
        "/opt/vps-guardian-mcp/.venv/bin/vps-guardian-mcp"
      ]
    }
  }
}

4. 🧠 OpenAI Codex / ChatGPT Desktop

Configure in your local MCP configuration file:

{
  "mcpServers": {
    "vps-guardian": {
      "command": "ssh",
      "args": [
        "-q",
        "-i", "~/.ssh/id_ed25519",
        "-o", "StrictHostKeyChecking=yes",
        "-o", "ServerAliveInterval=15",
        "-o", "ServerAliveCountMax=4",
        "root@<YOUR_VPS_IP>",
        "/opt/vps-guardian-mcp/.venv/bin/vps-guardian-mcp"
      ]
    }
  }
}

5. 🌊 Codeium Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "vps-guardian": {
      "command": "ssh",
      "args": [
        "-q",
        "-i", "~/.ssh/id_ed25519",
        "-o", "StrictHostKeyChecking=yes",
        "-o", "ServerAliveInterval=15",
        "-o", "ServerAliveCountMax=4",
        "root@<YOUR_VPS_IP>",
        "/opt/vps-guardian-mcp/.venv/bin/vps-guardian-mcp"
      ]
    }
  }
}

🛠️ Tools Reference (88 Active Tools)

📡 MCP Resources & Prompts

Resources

• vps://system-overview: Continuous live JSON system snapshot including per-core CPU, RAM, swap, disk I/O, network telemetry, and ambient operating system patch warnings.
• vps://security-dashboard: Unified security telemetry consolidating UFW firewall status, Fail2ban jails, recent failed authentication attempts, and open listening ports.
• vps://docker-overview: Live multi-container overview aggregating Docker daemon status, container inventories, health metrics, and disk space reclamation opportunities.

Prompts

• triage_server_incident: Systematic runbook guiding the AI step-by-step through incident investigation (CPU/RAM, failed systemd units, journal errors, authentication logs).
• emergency_disk_cleanup: Guided procedure for identifying disk space saturation (>90%) and safely applying bounded log vacuums, container caches, and APT cleanup.
• security_and_update_audit: Comprehensive security auditing routine assessing CVE patches, SSH daemon settings, brute-force activity, and cron task integrity.
• troubleshoot_application_crash: Incident diagnosis runbook investigating Out-Of-Memory terminations, kernel hardware/storage errors, and database reachability.

🔒 Security Architecture

1. No Shell Invocations: Subprocess executions consistently use explicit argument arrays (shell=False) to prevent command injection.
2. Strict Parameter Validation: Service identifiers, container names, and filters are validated against restrictive regex patterns.
3. Directory Path Whitelisting: File and backup operations are strictly locked down to /etc/nginx/, /etc/mysql/, /etc/postgresql/, /etc/docker/, /etc/caddy/, and /var/www/. Path traversal (../) is blocked at canonical resolution.
4. Atomic File Modifications: File writing stages changes via temporary files before atomic replacement to prevent file corruption.
5. Process Safety Controls: The process killer rejects requests targeting PID 1, init, sshd, or vital core operating system processes.
6. Immutable Whitelists: Execution actions are governed by fixed lookup tables.
7. Graceful Permission Degradation: Missing capabilities return descriptive diagnostic payloads rather than crashing the protocol stream.
8. Server-Side Safety Modes: Read-only is the default; controlled mode requires exact, short-lived, single-use confirmation tokens.
9. Redacted Audit Trail: Every completed state-changing operation writes a JSONL audit event without file contents, credentials, or confirmation tokens.

📄 License

Distributed under the MIT License. See LICENSE for more information.

Copyright (c) 2026 murzirius.