vServer Monitoring MCP Server

An MCP server (Model Context Protocol) that gives Claude SSH-based, read-only access to a Linux vServer. Claude can query system metrics, read log files, collect network information and produce complete health check reports.

Purpose

Monitoring a Linux server usually requires SSH access and knowing the relevant commands and log locations. This MCP server hides that complexity: it connects to the server over SSH and returns structured monitoring data. You can simply ask "How is my server doing?" in a chat and get a complete health check report, including automatic warnings when configured thresholds are exceeded.

Related MCP server: ai-ssh-mcp

Available tools

All tools support the output formats markdown (readable, default) and json (structured, for further processing).

Requirements

• Python 3.12+

• SSH access to the target server with an SSH key (RSA, Ed25519 or ECDSA)

• The public key must be listed in ~/.ssh/authorized_keys on the target server

• Standard Linux tools on the target server (cat, free, df, ss, ip, tail, uptime)

Installation

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Alternatively, use the install script:

./install.sh

Configuration

Copy config.example.yaml to config.yaml and adjust the values:

server:
  host: "your-server.example.com"
  port: 22
  username: "monitoring"
  ssh_key_path: "~/.ssh/id_ed25519"
  # ssh_key_passphrase: "passphrase-if-encrypted"
  timeout: 10

monitoring:
  logs:
    - path: "/var/log/syslog"
      name: "syslog"
      description: "System log with general system messages"
    - path: "/var/log/auth.log"
      name: "auth"
      description: "Authentication and authorization log"
    # Add more logs as needed:
    # - path: "/var/log/nginx/error.log"
    #   name: "nginx-error"

  network:
    check_ports: true
    check_connections: true

  system:
    thresholds:
      cpu_warning: 80
      cpu_critical: 95
      memory_warning: 80
      memory_critical: 95
      disk_warning: 80
      disk_critical: 95

config.yaml must be located in the same directory as vserver_mcp.py. It contains your server details and is excluded from version control via .gitignore.

Testing the connection

python3 test_connection.py

This script connects to the server configured in config.yaml. The unit tests in test_vserver_mcp.py run without a server:

python -m unittest test_vserver_mcp -v

Claude Desktop integration

{
  "mcpServers": {
    "vserver-monitoring": {
      "command": "/path/to/vserver_monitoring_mcp/.venv/bin/python",
      "args": [
        "/path/to/vserver_monitoring_mcp/vserver_mcp.py"
      ]
    }
  }
}

The configuration file is located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Important: The path in args must be absolute. On startup the server changes into the directory of the script, so that config.yaml is found.

See QUICKSTART.md and INTEGRATION.md for details.

Example prompts

Show me the current system metrics of my server.

Run a full health check and report any potential problems.

Show me the last 50 lines of the auth log.

Which ports are open on my server?

Security

The server executes read-only monitoring commands on the target host over SSH (for example free, df, ss, tail). It does not change anything on the server. Even so, it holds a working SSH key, so:

• Use a dedicated, unprivileged user instead of root, with read access only to the log files you want to expose.

• Use a dedicated SSH key for this purpose. Consider restricting it in authorized_keys (for example with from="...", no-port-forwarding, no-agent-forwarding, no-pty).

• Only list log files in config.yaml that you are comfortable sharing with the AI assistant.

Status

Beta. Usable for standard Linux servers (Debian/Ubuntu).

Contributing

See CONTRIBUTING.md.

License

MIT, see LICENSE. The name is not covered by the license.