# VPS Guardian (pypi · vps-guardian-mcp)

Secure SSH bridge for AI agents to observe and safely administer Linux VPSs.

- Trust score: 67/100 (medium)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-09-20

## Components

- npm · `@murzirius/vps-guardian-mcp`: 49/100, [markdown](https://verifymcp.io/servers/murzirius-vps-guardian-mcp/murzirius-vps-guardian-mcp.md), [page](https://verifymcp.io/servers/murzirius-vps-guardian-mcp/murzirius-vps-guardian-mcp)
- pypi · `vps-guardian-mcp`: 67/100 (this document), [markdown](https://verifymcp.io/servers/murzirius-vps-guardian-mcp/vps-guardian-mcp.md), [page](https://verifymcp.io/servers/murzirius-vps-guardian-mcp/vps-guardian-mcp)

## Channel facts

- Registry: `pypi`
- Package: `vps-guardian-mcp`
- Version: `0.21.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-09-20.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs setuptools.build_meta at install time, a recognised native-build step with no shell scripting around it.
  - 0 of 34 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 32/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - License check failed: no license is declared.
  - Actively maintained (last published 2 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 79/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (good).
  - Tool/resource definitions use about 6449 tokens (~63/item across 102 items; 99 tools + 3 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 13/100
  - Stability observed for 4 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 71/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 0% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Tool Safety**: 75/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - 0 of 2 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "deploy_config_change" implies "deploy" and declares no destructiveHint at all, which the MCP spec reads as destructive by default.
  - An AI judge read all 101 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the VPS Guardian MCP server?

VPS Guardian runs locally as a PyPI package, launched with uvx vps-guardian-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add murzirius-vps-guardian-mcp -- uvx vps-guardian-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "murzirius-vps-guardian-mcp": {
      "command": "uvx",
      "args": [
        "vps-guardian-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "murzirius-vps-guardian-mcp": {
      "command": "uvx",
      "args": [
        "vps-guardian-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add murzirius-vps-guardian-mcp -- uvx vps-guardian-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "murzirius-vps-guardian-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "vps-guardian-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add murzirius-vps-guardian-mcp --command uvx --arg vps-guardian-mcp
```

### Hermes

```yaml
mcp_servers:
  murzirius-vps-guardian-mcp:
    command: "uvx"
    args: ["vps-guardian-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "murzirius-vps-guardian-mcp": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "vps-guardian-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add murzirius-vps-guardian-mcp -t stdio -c uvx -a vps-guardian-mcp
```

### Other

```json
{
  "mcpServers": {
    "murzirius-vps-guardian-mcp": {
      "command": "uvx",
      "args": [
        "vps-guardian-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-09-20 (score 67, +1)

No change was recorded against any check on this day. Stability & Change Management went from 10 to 13. That category is still filling its 30-day observation window: 3 days of observed history at the previous scan, 4 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-18 (score 66, +1)

No change was recorded against any check on this day. Stability & Change Management went from 3 to 7. That category is still filling its 30-day observation window: 1 days of observed history at the previous scan, 2 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-17 (score 65, 0)

- [security regression] Tool safety: pass → unverified
- [security regression] Malware scan: pass → unverified
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional regression] Capabilities: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Schema quality: 100 → unverified
- [functional improvement] Stability: unverified → 0.03
- [functional] Package version: 0.19.1 → 0.21.0
- [functional] Package version: 0.19.1 → 0.20.1

### 2026-09-16 (score 65)

First indexed and scored.

## MCP tools (99)

### `get_system_health` (~117 tokens)

Retrieve a complete system health snapshot of the Linux VPS.

Returns a JSON string containing:
\- CPU: overall percentage, per-core breakdown, core counts, 1/5/15m load averages.
\- RAM & Swap: total, used, available, percentage.
\- Disk: root partition usage, read/write I/O counters.
\- Network: sent/received bytes, packets, and error counts.
\- Uptime: boot timestamp and human-readable duration (e.g. '12d 4h 32m 10s').

Output parameters:

- `result` (string)

### `get_top_processes` (~103 tokens)

Retrieve the top resource-consuming processes running on the VPS.

Args:
    sort_by: Metric to rank processes by ('cpu' or 'memory'). Default: 'cpu'.
    limit: Number of top processes to return (1 to 50, default: 10).

Returns:
    JSON string listing process PID, name, user, CPU %, RAM %, RSS memory, and command summary.

Input parameters:

- `limit` (integer)
- `sort_by` (string)

Output parameters:

- `result` (string)

### `check_service_status` (~87 tokens)

Check the operational status of a systemd service unit.

Args:
    service_name: Name of the system service (e.g. 'nginx', 'mysql', 'postgresql', 'ufw', 'docker').

Returns:
    JSON string with active state ('active', 'inactive', 'failed'), enabled state, and recent status logs.

Input parameters:

- `service_name` (string, required)

Output parameters:

- `result` (string)

### `get_failed_systemd_units` (~45 tokens)

Find all degraded or failed systemd services across the entire system.

Returns:
    JSON string with list of failed units ('systemctl --failed') and overall health indicator.

Output parameters:

- `result` (string)

### `read_service_logs` (~138 tokens)

Safely fetch and optionally filter recent log lines for a service or Docker container.

Args:
    service_name: Target unit (e.g. 'nginx', 'systemd:cron', 'docker:my_container').
    lines_count: Number of recent lines to retrieve (default: 50, maximum: 1000).
    grep_filter: Optional case-insensitive keyword to filter lines (e.g. 'ERROR', '403', 'denied').

Returns:
    JSON string containing the extracted log lines and matching statistics.

Input parameters:

- `grep_filter`
- `lines_count` (integer)
- `service_name` (string, required)

Output parameters:

- `result` (string)

### `get_process_details` (~73 tokens)

In-depth diagnostics for a specific PID: hierarchy, threads, memory, open files, sockets, I/O.

Args:
    pid: The target process ID to inspect (positive integer).

Returns:
    JSON string detailing process tree, memory breakdown, sockets, files, and sanitized env.

Input parameters:

- `pid` (integer, required)

Output parameters:

- `result` (string)

### `detect_zombie_processes` (~45 tokens)

Scan system process table for defunct/zombie processes and identify non-reaping parents.

Returns:
    JSON string reporting detected zombies, parent PIDs, and remediation advice.

Output parameters:

- `result` (string)

### `check_system_limits` (~47 tokens)

Audit system-wide and user limits: file descriptors, max PIDs, virtual memory, socket backlogs.

Returns:
    JSON string comparing allocations to kernel limits and highlighting threshold warnings (>80%).

Output parameters:

- `result` (string)

### `list_docker_containers` (~74 tokens)

List Docker containers with their status, image, port bindings, volumes, and health.

Args:
    all: Set to True to list all containers (running and stopped), False for running only.

Returns:
    JSON string with list of containers, port forwards, and mount mappings.

Input parameters:

- `all` (boolean)

Output parameters:

- `result` (string)

### `get_docker_container_logs` (~87 tokens)

Safely read stdout/stderr logs from a specific Docker container.

Args:
    container_name: Container name or container short/full ID.
    lines_count: Number of recent log lines to retrieve (default: 50, max: 1000).

Returns:
    JSON string containing the container logs.

Input parameters:

- `container_name` (string, required)
- `lines_count` (integer)

Output parameters:

- `result` (string)

### `get_docker_stats` (~57 tokens)

Retrieve live resource utilization metrics for all running Docker containers.

Provides real-time CPU %, Memory %, Network I/O, and Block I/O (equivalent to `docker stats`).

Returns:
    JSON string listing resource metrics per running container.

Output parameters:

- `result` (string)

### `docker_container_action` (~145 tokens)

Safely execute lifecycle operations (start, stop, restart, pause, unpause) on a container.

Args:
    container_name: Name or short/full ID of the target Docker container.
    action: Desired action ('start', 'stop', 'restart', 'pause', 'unpause').
    timeout: Stop/restart timeout in seconds before forcible kill (default: 10).
    confirmation_token: Single-use token returned by the preceding plan call.

Returns:
    JSON string detailing previous status, new status, and action outcome.

Input parameters:

- `action` (string, required)
- `confirmation_token`
- `container_name` (string, required)
- `timeout` (integer)

Output parameters:

- `result` (string)

### `inspect_docker_container` (~67 tokens)

Deep inspection of container networks, volume mounts, restart policy, healthcheck, and masked env vars.

Args:
    container_name: Name or short/full ID of the target container.

Returns:
    JSON string detailing full container architecture and runtime state.

Input parameters:

- `container_name` (string, required)

Output parameters:

- `result` (string)

### `clean_docker_garbage` (~104 tokens)

Safely reclaim disk space by pruning dangling images, stopped containers, unused volumes, and networks.

Args:
    prune_type: Category to prune ('containers', 'images', 'volumes', 'networks', 'all'). Default is 'all'.
    confirmation_token: Single-use token returned by the preceding plan call.

Returns:
    JSON string detailing deleted items and total disk capacity reclaimed.

Input parameters:

- `confirmation_token`
- `prune_type` (string)

Output parameters:

- `result` (string)

### `list_compose_projects` (~37 tokens)

Discover conventional Docker Compose files in an authorized directory tree.

Input parameters:

- `max_depth` (integer)
- `root_path` (string)

Output parameters:

- `result` (string)

### `inspect_compose_project` (~34 tokens)

Return Docker Compose service topology, images, ports, dependencies, and healthchecks.

Input parameters:

- `compose_file` (string, required)

Output parameters:

- `result` (string)

### `compose_project_action` (~51 tokens)

Token-confirmed Docker Compose up, restart, or stop for selected project services.

Input parameters:

- `action` (string, required)
- `compose_file` (string, required)
- `confirmation_token`
- `services`

Output parameters:

- `result` (string)

### `get_vps_topology` (~58 tokens)

Map websites, reverse proxies, Compose projects, containers, ports, and databases.

The map is read-only and excludes configuration content, environment values,
and credentials. Use it before diagnosing an application whose location on
the VPS is unknown.

Output parameters:

- `result` (string)

### `find_workload` (~33 tokens)

Find an application by domain, container, Compose service, port, or path fragment.

Input parameters:

- `query` (string, required)

Output parameters:

- `result` (string)

### `get_workload_health` (~33 tokens)

Return concise health, resource, container, and matching SSL state for one workload.

Input parameters:

- `target` (string, required)

Output parameters:

- `result` (string)

### `diagnose_workload` (~42 tokens)

Gather bounded read-only logs, OOM, kernel, and health evidence for a workload.

Input parameters:

- `log_lines` (integer)
- `target` (string, required)

Output parameters:

- `result` (string)

### `get_change_impact` (~54 tokens)

Show what a prospective restart, stop, config deployment, or update may affect.

This tool never executes the action and does not issue a confirmation token.

Input parameters:

- `action` (string)
- `target` (string, required)

Output parameters:

- `result` (string)

### `prepare_repair_plan` (~28 tokens)

Create an evidence-backed repair plan without changing the VPS.

Input parameters:

- `target` (string, required)

Output parameters:

- `result` (string)

### `create_workload_baseline` (~36 tokens)

Save a secret-free known-good workload baseline for later drift comparison.

Input parameters:

- `label`
- `target` (string, required)

Output parameters:

- `result` (string)

### `compare_workload_baseline` (~30 tokens)

Compare a saved workload baseline with the current workload state.

Input parameters:

- `baseline_id` (string, required)

Output parameters:

- `result` (string)

### `start_agent_session` (~46 tokens)

Create an expiring, secret-safe shared task context for agents working on this VPS.

Input parameters:

- `target`
- `title` (string, required)
- `ttl_minutes` (integer)

Output parameters:

- `result` (string)

### `get_agent_session` (~33 tokens)

Read a session's objective, findings, handoff note, and expiry state.

Input parameters:

- `session_id` (string, required)

Output parameters:

- `result` (string)

### `list_agent_sessions` (~29 tokens)

List active shared agent sessions; expired sessions are marked automatically.

Input parameters:

- `include_closed` (boolean)

Output parameters:

- `result` (string)

### `record_session_finding` (~48 tokens)

Save one bounded, secret-redacted finding or decision to an active agent session.

Input parameters:

- `kind` (string)
- `session_id` (string, required)
- `summary` (string, required)

Output parameters:

- `result` (string)

### `handoff_agent_session` (~48 tokens)

Leave a concise handoff note so another agent can continue without rediscovery.

Input parameters:

- `next_agent` (string, required)
- `session_id` (string, required)
- `summary` (string, required)

Output parameters:

- `result` (string)

### `close_agent_session` (~38 tokens)

Close a session with an outcome; historical records remain secret-redacted.

Input parameters:

- `outcome` (string, required)
- `session_id` (string, required)

Output parameters:

- `result` (string)

### `lock_workload` (~45 tokens)

Reserve a workload briefly so concurrent agents do not make conflicting changes.

Input parameters:

- `session_id` (string, required)
- `target` (string, required)
- `ttl_minutes` (integer)

Output parameters:

- `result` (string)

### `get_recent_server_events` (~42 tokens)

Return a compact timeline of Guardian actions and important journal events.

Input parameters:

- `limit` (integer)
- `since_minutes` (integer)
- `target`

Output parameters:

- `result` (string)

### `open_event_watch` (~47 tokens)

Open an expiring workload watch. Use get_event_watch later to retrieve new events.

Input parameters:

- `session_id`
- `target` (string, required)
- `ttl_minutes` (integer)

Output parameters:

- `result` (string)

### `get_event_watch` (~41 tokens)

Retrieve events seen since an active event watch was opened; this does not push notifications.

Input parameters:

- `limit` (integer)
- `watch_id` (string, required)

Output parameters:

- `result` (string)

### `begin_change_set` (~36 tokens)

Open a short-lived, bounded, reversible Nginx configuration ChangeSet.

Input parameters:

- `target`
- `title` (string, required)

Output parameters:

- `result` (string)

### `stage_file_change` (~47 tokens)

Stage one Nginx configuration change; content is not applied yet.

Input parameters:

- `change_set_id` (string, required)
- `content` (string, required)
- `file_path` (string, required)

Output parameters:

- `result` (string)

### `preview_change_set` (~33 tokens)

Show secret-redacted diffs and request one confirmation for a ChangeSet.

Input parameters:

- `change_set_id` (string, required)

Output parameters:

- `result` (string)

### `apply_change_set` (~41 tokens)

Apply, validate, reload, health-check, and automatically roll back one ChangeSet.

Input parameters:

- `change_set_id` (string, required)
- `confirmation_token`

Output parameters:

- `result` (string)

### `get_runtime_budget` (~25 tokens)

Show the active low-resource profile and limits VPS-Guardian applies on this host.

Output parameters:

- `result` (string)

### `create_maintenance_window` (~84 tokens)

Create an expiring maintenance window for agent coordination.

A window records intent and timing; it never bypasses the active safety
mode or grants permission for VPS changes.

Input parameters:

- `allowed_actions`
- `duration_minutes` (integer)
- `session_id`
- `starts_in_minutes` (integer)
- `target`
- `title` (string, required)

Output parameters:

- `result` (string)

### `list_maintenance_windows` (~30 tokens)

List active maintenance windows, or include closed and expired history.

Input parameters:

- `include_closed` (boolean)

Output parameters:

- `result` (string)

### `close_maintenance_window` (~37 tokens)

Close a maintenance window with a secret-redacted outcome note.

Input parameters:

- `outcome` (string)
- `window_id` (string, required)

Output parameters:

- `result` (string)

### `watch_resource_threshold` (~74 tokens)

Create an expiring CPU, memory, swap, or disk threshold watch.

The watch has no background worker. Call get_resource_alerts to evaluate it
on demand, which is safe for small VPS instances.

Input parameters:

- `metric` (string, required)
- `threshold_percent` (number, required)
- `ttl_minutes` (integer)

Output parameters:

- `result` (string)

### `get_resource_alerts` (~28 tokens)

Evaluate active resource watches once and return current threshold alerts.

Input parameters:

- `limit` (integer)

Output parameters:

- `result` (string)

### `list_runbook_templates` (~23 tokens)

List command-free agent runbooks built from existing guarded MCP tools.

Output parameters:

- `result` (string)

### `start_runbook` (~50 tokens)

Open a bounded agent runbook; it never runs commands or bypasses confirmation.

Input parameters:

- `session_id`
- `target`
- `template` (string, required)
- `title` (string)

Output parameters:

- `result` (string)

### `update_runbook_step` (~55 tokens)

Record the outcome of one runbook step after its separate guarded tool call.

Input parameters:

- `note` (string)
- `run_id` (string, required)
- `status` (string, required)
- `step_id` (integer, required)

Output parameters:

- `result` (string)

### `list_runbooks` (~28 tokens)

List active agent runbooks, with optional completed history.

Input parameters:

- `include_closed` (boolean)

Output parameters:

- `result` (string)

### `discover_projects` (~33 tokens)

Find bounded Git/application projects in configured VPS project roots.

Input parameters:

- `max_depth` (integer)
- `root_path`

Output parameters:

- `result` (string)

### `inspect_project` (~33 tokens)

Inspect an approved project: stack markers, Git branch/commit, and dirty state.

Input parameters:

- `project_path` (string, required)

Output parameters:

- `result` (string)

### `search_project_code` (~46 tokens)

Bounded literal code search with ignored dependency folders and redacted output.

Input parameters:

- `max_matches` (integer)
- `project_path` (string, required)
- `query` (string, required)

Output parameters:

- `result` (string)

### `read_project_file` (~50 tokens)

Read one non-binary project file without following symlinks; redact common secrets.

Input parameters:

- `max_bytes` (integer)
- `project_path` (string, required)
- `relative_path` (string, required)

Output parameters:

- `result` (string)

### `begin_project_patch` (~38 tokens)

Open a short-lived, bounded source patch; no project code runs.

Input parameters:

- `project_path` (string, required)
- `title` (string, required)

Output parameters:

- `result` (string)

### `stage_project_file_change` (~47 tokens)

Stage one source-file replacement in an active project patch without applying it.

Input parameters:

- `content` (string, required)
- `patch_id` (string, required)
- `relative_path` (string, required)

Output parameters:

- `result` (string)

### `preview_project_patch` (~32 tokens)

Show secret-redacted source diff and obtain one confirmation token for a patch.

Input parameters:

- `patch_id` (string, required)

Output parameters:

- `result` (string)

### `apply_project_patch` (~38 tokens)

Apply a confirmed bounded source patch with backups; it never executes project code.

Input parameters:

- `confirmation_token`
- `patch_id` (string, required)

Output parameters:

- `result` (string)

### `get_project_changes` (~30 tokens)

Read Git working-tree changes and diff statistics without modifying the project.

Input parameters:

- `project_path` (string, required)

Output parameters:

- `result` (string)

### `run_project_checks` (~39 tokens)

Run only fixed safe checks: Git whitespace validation or bounded Python syntax parsing.

Input parameters:

- `check` (string)
- `project_path` (string, required)

Output parameters:

- `result` (string)

### `get_open_ports` (~55 tokens)

Discover all listening network ports (TCP and UDP) and identify bound processes.

Returns:
    JSON string listing open ports, protocols (TCP/UDP), binding addresses (IPv4/IPv6),
    and process names/PIDs.

Output parameters:

- `result` (string)

### `get_ufw_status` (~48 tokens)

Inspect the status and active filtering rules of the UFW firewall.

Returns:
    JSON string containing UFW active state, default incoming/outgoing policies,
    and all active firewall rules.

Output parameters:

- `result` (string)

### `get_platform_capabilities` (~27 tokens)

Detect package, firewall, service-manager, and Docker Compose backends on this host.

Output parameters:

- `result` (string)

### `get_package_updates` (~33 tokens)

List available updates via APT, DNF, YUM, Pacman, or Zypper without changing state.

Output parameters:

- `result` (string)

### `get_firewall_status` (~27 tokens)

Return normalized UFW, firewalld, or nftables firewall state and rules.

Output parameters:

- `result` (string)

### `view_file_content` (~132 tokens)

Safely read the content of an authorized configuration or web file.

Permitted directories: /etc/nginx/, /etc/mysql/, /etc/postgresql/, /etc/docker/, /etc/caddy/, /var/www/
Strictly protected against path traversal attacks.

Args:
    file_path: Canonical path or relative path to the configuration file.
    max_bytes: Maximum bytes to return (default: 50,000, capped at 200,000).

Returns:
    JSON string with file content, size, and modification timestamp.

Input parameters:

- `file_path` (string, required)
- `max_bytes` (integer)

Output parameters:

- `result` (string)

### `write_file_content` (~156 tokens)

Atomically write or update a configuration file within authorized directories.

Creates an automatic timestamped backup (.bak.<timestamp>) before overwriting.
Permitted directories: /etc/nginx/, /etc/mysql/, /etc/postgresql/, /etc/docker/, /etc/caddy/, /var/www/

Args:
    file_path: Path to the target configuration file.
    content: Text content to write.
    backup: Create a backup file before writing (default: True).
    confirmation_token: Single-use token returned by the preceding plan call.

Returns:
    JSON string indicating write status and backup location.

Input parameters:

- `backup` (boolean)
- `confirmation_token`
- `content` (string, required)
- `file_path` (string, required)

Output parameters:

- `result` (string)

### `set_web_file_mode` (~79 tokens)

Set a safe web-readable mode (0644 or 0640) for a static file under /var/www.

The content is untouched; arbitrary chmod modes and paths outside /var/www
are rejected. Controlled mode requires a confirmation token.

Input parameters:

- `confirmation_token`
- `file_path` (string, required)
- `mode` (string)

Output parameters:

- `result` (string)

### `list_directory` (~113 tokens)

Inspect file and directory structures within authorized administrative paths.

Permitted directories: /etc/nginx/, /etc/mysql/, /etc/postgresql/, /etc/docker/, /etc/caddy/, /var/www/

Args:
    dir_path: Path to the directory to inspect.
    max_depth: Exploration depth (1 to 3, default: 1).

Returns:
    JSON string with item list (names, types, sizes, modification dates).

Input parameters:

- `dir_path` (string, required)
- `max_depth` (integer)

Output parameters:

- `result` (string)

### `plan_config_deployment` (~171 tokens)

Validate and preview an Nginx config or Caddyfile deployment.

The candidate is staged outside the live path, syntax-checked, and shown as
a bounded unified diff. No live configuration is modified. Nginx configs
under /etc/nginx and Caddyfiles under /etc/caddy are supported.

Args:
    file_path: Target config path under /etc/nginx or /etc/caddy.
    content: Complete proposed UTF-8 configuration (at most 200,000 bytes).
    service_name: Optional matching service name (nginx or caddy).

Returns:
    JSON plan with validation output, diff, expiry, and a confirmation token
    in controlled mode.

Input parameters:

- `content` (string, required)
- `file_path` (string, required)
- `service_name`

Output parameters:

- `result` (string)

### `deploy_config_change` (~89 tokens)

Commit a validated configuration plan, reload its service, and auto-rollback on failure.

Args:
    deployment_id: Short-lived identifier returned by plan_config_deployment.
    confirmation_token: Required only in controlled mode; bound to this plan.

Returns:
    JSON outcome with atomic-write, reload, health-check, and rollback details.

Input parameters:

- `confirmation_token`
- `deployment_id` (string, required)

Output parameters:

- `result` (string)

### `create_system_snapshot` (~79 tokens)

Save a privacy-preserving, read-only VPS state baseline.

Records ports, failed units, cron/timers, Docker inventory, and optional
configuration file hashes. It never stores config content or cron commands.
Snapshot storage is configurable with VPS_GUARDIAN_SNAPSHOT_DIR.

Input parameters:

- `include_config_hashes` (boolean)
- `label`

Output parameters:

- `result` (string)

### `list_system_snapshots` (~28 tokens)

List stored VPS state snapshots without exposing their collected content.

Input parameters:

- `limit` (integer)

Output parameters:

- `result` (string)

### `compare_system_snapshots` (~68 tokens)

Compare two snapshots and rank configuration or infrastructure drift by risk.

Flags new exposed ports, failed units, cron changes, Docker drift, and
configuration-hash changes. Both snapshots must be from the same host.

Input parameters:

- `baseline_id` (string, required)
- `current_id` (string, required)

Output parameters:

- `result` (string)

### `test_nginx_config` (~45 tokens)

Test Nginx configuration for syntax errors ('nginx -t') without reloading.

Returns:
    JSON string indicating syntax validity, exit code, and syntax error messages.

Output parameters:

- `result` (string)

### `check_http_endpoint` (~87 tokens)

Check a public HTTP(S) URL: response status, redirects, TLS, latency, and optional text.

This is read-only and intentionally returns only metadata, never a page body.
Use it before or after a deployment to verify the public result.

Input parameters:

- `expected_status` (integer)
- `expected_text`
- `timeout_seconds` (integer)
- `url` (string, required)

Output parameters:

- `result` (string)

### `check_http_endpoints` (~65 tokens)

Check up to 20 public HTTP(S) endpoints in one compact deployment health report.

Each item accepts url, expected_status (default 200), expected_text (optional),
and timeout_seconds (default 10). This tool is read-only.

Input parameters:

- `endpoints` (array, required)

Output parameters:

- `result` (string)

### `get_web_deployment_status` (~81 tokens)

Verify one website end to end: public HTTPS response, local Nginx host, and certificate.

Returns a single diagnosis identifying whether an issue is public availability,
virtual-host configuration, or the matching TLS certificate.

Input parameters:

- `domain` (string, required)
- `expected_status` (integer)
- `expected_text`
- `path` (string)

Output parameters:

- `result` (string)

### `check_ssl_certificates` (~44 tokens)

Audit SSL/TLS certificates configured on the host (Let's Encrypt / Certbot).

Returns:
    JSON string listing domains, expiration dates, days remaining, and warning flags.

Output parameters:

- `result` (string)

### `list_virtual_hosts` (~48 tokens)

Inspect active Nginx virtual hosts, listening ports, SSL, and reverse proxy targets.

Returns:
    JSON string with parsed virtual hosts from /etc/nginx/sites-enabled/ and conf.d/.

Output parameters:

- `result` (string)

### `check_failed_logins` (~69 tokens)

Inspect recent failed SSH login attempts to detect brute-force attackers.

Args:
    limit: Number of recent failed attempts to inspect (default: 20, max: 100).

Returns:
    JSON string with recent failed logins and top offending attacker IP addresses.

Input parameters:

- `limit` (integer)

Output parameters:

- `result` (string)

### `get_fail2ban_status` (~42 tokens)

Check Fail2ban status, active protection jails, and currently banned IP addresses.

Returns:
    JSON string detailing active jails and banned IP addresses.

Output parameters:

- `result` (string)

### `audit_ssh_config` (~40 tokens)

Audit the SSH daemon configuration against security best practices.

Returns:
    JSON string with detected settings, security score (0-100), and remediation guidance.

Output parameters:

- `result` (string)

### `analyze_disk_usage` (~180 tokens)

Analyze disk usage for a directory to discover space bottlenecks and large files.

Safely walks the filesystem without following symlinks and automatically skips
virtual pseudo-filesystems (/proc, /sys, /dev, /run).

Args:
    target_path: Starting path to inspect (defaults to '/var').
    max_depth: Depth of directory nesting to inspect (1 to 5, default 2).
    min_size_mb: Minimum size threshold in megabytes to include (default 50 MB).
    top_n: Maximum number of largest items to return (1 to 50, default 15).

Returns:
    JSON string with partition usage, largest directories, and largest files.

Input parameters:

- `max_depth` (integer)
- `min_size_mb` (integer)
- `target_path` (string)
- `top_n` (integer)

Output parameters:

- `result` (string)

### `list_cron_jobs` (~71 tokens)

Discover all scheduled cron jobs on the Linux system.

Audits /etc/crontab, /etc/cron.d/, /etc/cron.* periodic scripts, and user crontabs.

Returns:
    JSON string containing scheduled jobs with user, schedule expression,
    human-readable timing explanation, and command.

Output parameters:

- `result` (string)

### `list_systemd_timers` (~46 tokens)

Audit active and pending systemd timers via 'systemctl list-timers'.

Returns:
    JSON string with timer unit names, next execution time, countdown, and target services.

Output parameters:

- `result` (string)

### `check_system_updates` (~103 tokens)

Audit available operating system package updates and pending security patches.

Checks reboot requirements (/var/run/reboot-required), total upgradable packages,
and security CVE patches. Cached for 5 minutes to minimize CPU and disk usage.

Args:
    force_refresh: Set to True to bypass the 5-minute cache and query package managers directly.

Returns:
    JSON string with update counts, security status, reboot flag, and recommended recovery action.

Input parameters:

- `force_refresh` (boolean)

Output parameters:

- `result` (string)

### `check_guardian_updates` (~101 tokens)

Check if a newer version or commit of VPS-Guardian-MCP is available on GitHub.

Provides automated version verification and action guidance for self-updating.
Cached for 5 minutes to minimize network and CPU overhead.

Args:
    force_refresh: Set to True to bypass cache and query GitHub API directly.

Returns:
    JSON string with current version, latest commit, update availability,
    and AI warning notice.

Input parameters:

- `force_refresh` (boolean)

Output parameters:

- `result` (string)

### `check_oom_events` (~89 tokens)

Inspect kernel logs for Linux Out-Of-Memory (OOM) Killer invocations.

Surfaces terminated processes, PIDs, and consumed RSS memory at time of termination.

Args:
    limit: Maximum number of recent OOM events to return (1 to 50, default 10).

Returns:
    JSON string with detected OOM incidents and diagnostic summary.

Input parameters:

- `limit` (integer)

Output parameters:

- `result` (string)

### `check_kernel_errors` (~74 tokens)

Audit kernel logs for hardware failures, storage I/O errors, or application segfaults.

Args:
    limit: Maximum number of error entries to retrieve (1 to 50, default 20).

Returns:
    JSON string with categorized kernel errors, root causes, and critical issue counters.

Input parameters:

- `limit` (integer)

Output parameters:

- `result` (string)

### `test_network_connectivity` (~149 tokens)

Benchmark outbound network connectivity and latency using direct Python sockets.

Measures DNS resolution latency, TCP handshake time, and TLS handshake latency without shell ping.

Args:
    target_host: Destination hostname or IP address (e.g. 'api.github.com' or '8.8.8.8').
    port: Destination port (1-65535, default 443).
    timeout_seconds: Network socket timeout (0.5 to 30.0 seconds, default 5.0).

Returns:
    JSON string with stage latency breakdown, resolved IP addresses, and TLS session details.

Input parameters:

- `port` (integer)
- `target_host` (string, required)
- `timeout_seconds` (number)

Output parameters:

- `result` (string)

### `check_dns_health` (~67 tokens)

Audit system DNS resolution health, configured nameservers, and query responsiveness.

Args:
    domains: Optional custom list of domains to probe. Defaults to essential public services.

Returns:
    JSON string with configured nameservers, individual domain lookup latencies, and health verdict.

Input parameters:

- `domains`

Output parameters:

- `result` (string)

### `get_database_health` (~61 tokens)

Discover running databases and verify responsiveness, latency, and socket states.

Detects Redis, PostgreSQL, MySQL/MariaDB, and SQLite databases in application directories.

Returns:
    JSON string with operational state, socket accessibility, and ping latency for each engine.

Output parameters:

- `result` (string)

### `generate_incident_report` (~99 tokens)

Generate one prioritized, read-only VPS incident report.

Args:
    include_updates: Include operating-system patch and reboot status.
    include_security: Include SSH hardening assessment.
    include_network: Include listening ports; disabled by default to keep reports compact.

Returns:
    JSON string with severity-ranked findings and the underlying diagnostic sections.

Input parameters:

- `include_network` (boolean)
- `include_security` (boolean)
- `include_updates` (boolean)

Output parameters:

- `result` (string)

### `get_safety_status` (~25 tokens)

Return the active safety mode, confirmation policy, TTL, and audit destination.

Output parameters:

- `result` (string)

### `get_audit_events` (~48 tokens)

Return recent redacted audit events for state-changing operations.

Args:
    limit: Number of newest events to return (1-500, default 50).

Input parameters:

- `limit` (integer)

Output parameters:

- `result` (string)

### `execute_recovery` (~296 tokens)

Execute an emergency recovery operation from a strictly whitelisted list.

Allowed actions:
\- 'restart_service': Restarts a systemd service (requires target=service_name, e.g. target='nginx').
\- 'clean_docker_cache': Deep prune of unused containers, networks, images, and volumes.
\- 'clean_system_logs': Prunes journal logs older than 3 days and rotated archives in /var/log.
\- 'kill_process': Terminates a runaway process by PID (requires target=PID, e.g. target='12345').
\- 'restart_nginx': Restarts Nginx web server (legacy alias for restart_service target='nginx').
\- 'vacuum_systemd_journal': Truncates journal logs to limit (target defaults to '200M').
\- 'clean_package_cache': Cleans APT archive cache and removes obsolete packages.
\- 'apply_security_updates': Non-interactively applies pending operating system security updates.
\- 'update_guardian': Self-updates VPS-Guardian-MCP from GitHub and refreshes virtual environment.

Args:
    action_name: The exact recovery action to execute.
    target: Optional target parameter required by certain actions.
    confirmation_token: Single-use token returned by the preceding plan call.

Returns:
    JSON string with operation outcome, freed resources, or security error.

Input parameters:

- `action_name` (string, required)
- `confirmation_token`
- `target`

Output parameters:

- `result` (string)

### `create_backup` (~159 tokens)

Create a compressed tar.gz archive of an authorized website or configuration directory.

Archives are saved into an isolated backup repository (/var/backups/vps-guardian/).
Permitted source locations: /var/www/, /etc/nginx/, /etc/mysql/, /etc/postgresql/, /etc/docker/, /etc/caddy/

Args:
    backup_type: Identifier label for the archive (e.g. 'site', 'config', 'data').
    source_path: Target directory to archive.
    confirmation_token: Single-use token returned by the preceding plan call.

Returns:
    JSON string with archive file path, size, file count, and duration.

Input parameters:

- `backup_type` (string, required)
- `confirmation_token`
- `source_path` (string, required)

Output parameters:

- `result` (string)

### `get_backup_status` (~30 tokens)

List isolated Guardian backups with sizes and creation times, without reading contents.

Input parameters:

- `limit` (integer)

Output parameters:

- `result` (string)

### `verify_backup` (~49 tokens)

Verify a Guardian tar.gz archive without extracting it.

Only regular archives within the isolated Guardian backup directory are
accepted. Very large member counts return a bounded partial result.

Input parameters:

- `archive_path` (string, required)

Output parameters:

- `result` (string)

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/murzirius-vps-guardian-mcp/vps-guardian-mcp#diagnostics

## Score history

- 2026-09-20: 67
- 2026-09-19: 66
- 2026-09-18: 66
- 2026-09-17: 65
- 2026-09-16: 65

## Common questions

### What is the VPS Guardian MCP server?

VPS Guardian is an MCP server listed in the public MCP registry as io.github.murzirius/vps-guardian-mcp. Secure SSH bridge for AI agents to observe and safely administer Linux VPSs. This page covers its PyPI package (vps-guardian-mcp).

### Is the VPS Guardian MCP server safe to use?

VPS Guardian scores 67 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 20 September 2026. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the VPS Guardian MCP server expose?

VPS Guardian exposes 99 tools: get_system_health, get_top_processes, check_service_status, get_failed_systemd_units, read_service_logs, and 94 more. Their descriptions and schemas cost roughly 6,292 tokens of context every time the server is loaded.

### Is the VPS Guardian MCP server still maintained?

VPS Guardian is still listed as active in the MCP registry. We last reached this channel on 20 September 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

## Links

- PyPI project: https://pypi.org/project/vps-guardian-mcp/
- Socket report: https://socket.dev/pypi/package/vps-guardian-mcp
- Repository: https://github.com/murzirius/VPS-Guardian-MCP
- Changelog RSS feed: https://verifymcp.io/servers/murzirius-vps-guardian-mcp/vps-guardian-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/murzirius-vps-guardian-mcp/vps-guardian-mcp.json
- HTML version of this page: https://verifymcp.io/servers/murzirius-vps-guardian-mcp/vps-guardian-mcp