MCP System Health Monitoring

You monitor real-time health and performance metrics for remote Linux servers using an MCP-based System Health Monitor. It gathers CPU, memory, disk, network, and security metrics, enabling you to observe multiple servers from a single MCP instance and receive threshold-based alerts to keep your infrastructure healthy.

How to use

Use this MCP server to query health data from remote servers via an MCP client. You can start the local monitoring server, register one or more remote targets, and then invoke tools like system_status, cpu_metrics, memory_metrics, and others to fetch current metrics or a health summary. This enables proactive troubleshooting, capacity planning, and security insights across your fleet.

How to install

Prerequisites: ensure you have Python 3.10+ installed and you can access the MCP Python SDK. You also need SSH access to each target server you want to monitor.

Step 1: Clone the project and enter the directory.

git clone https://github.com/yourusername/mcp-system-health.git
cd mcp-system-health

Step 2: Create and activate a Python virtual environment.

python -m venv venv
# Activate the virtual environment
# macOS/Linux
source venv/bin/activate
# Windows
venv\Scripts\activate

Step 3: Install dependencies.

pip install -r requirements.txt

Additional configuration and usage notes

Configure a separate settings file for each server you want to monitor. The sample configuration shows how to specify the target’s hostname, IP, SSH port, user, and the SSH key path.

{
  "hostname": "server1",
  "ip": "192.168.1.100",
  "ssh_port": 22,
  "username": "admin",
  "key_path": "~/.ssh/id_rsa"
}

Launching the MCP server via the launcher

Use the launcher to start the MCP server and connect to one or more target servers. The launcher runs the MCP server in the current environment and passes SSH credentials and server addresses to monitor.

./mcp_launcher.py --username=admin --key-path=~/.ssh/id_rsa --servers=192.168.1.100,192.168.1.101

Integrating with an MCP client like Claude

To connect this MCP server to Claude, add the MCP server configuration to Claude’s MCP settings and restart for changes to take effect. The example shows how to configure the client to launch the launcher with credentials and server targets.

{
  "mcpServers": {
    "system-health": {
      "command": "/path/to/your/venv/bin/python3",
      "args": [
        "/path/to/your/system-health-mcp-server/src/mcp_launcher.py", 
        "--username=your_ssh_username", 
        "--password=your_ssh_password",
        "--key-path=~/.ssh/id_rsa",
        "--servers=server1.example.com,server2.example.com", 
        "--log-level=debug"
      ],
      "description": "System Health MCP Server for monitoring remote servers"
    }
  }
}

Using the Python library to start the MCP server

If you prefer embedding the server directly in a Python script, you can configure server connections and start the MCP server from code.

from src.server import serve

server_configs = [
    {
        "hostname": "server1",
        "ip": "192.168.1.100",
        "ssh_port": 22,
        "username": "admin",
        "password": "password",
        "key_path": "~/.ssh/id_rsa"
    }
]

#Start the MCP server
await serve(server_configs)

Security considerations

Prefer key-based authentication, use dedicated monitoring accounts with limited permissions, store SSH credentials securely, and run the MCP server on a secure, trusted host.

Troubleshooting

If you run into issues, verify SSH credentials, ensure target servers allow SSH connections, confirm the user can execute system commands, and enable verbose logging for more details.

Notes on capabilities and limitations

This MCP server offers real-time system health metrics, supports multiple servers, and provides threshold-based alerts for CPU, memory, disk, and security-related conditions. It does not store historical data and currently emphasizes real-time visibility and single-shot tool calls rather than a notification system.

Available tools

system_status

General system status information including uptime, load, and basic health indicators.

cpu_metrics

Detailed CPU usage statistics, including per-core utilization.

memory_metrics

Memory usage, cache, buffers, and swap statistics.

disk_metrics

Disk usage and inode metrics for mounts and devices.

network_metrics

Network interface statistics such as bytes in/out and errors.

security_metrics

Security-related metrics including failed logins and patch status.

process_list

List of top CPU-consuming processes.

system_alerts

Current alerts based on defined thresholds.

health_summary

Comprehensive health summary across all monitored servers.