SysMetrics MCP Server

A lightweight MCP (Model Context Protocol) server that exposes Linux system metrics through MCP tools. Works on any Linux system including Raspberry Pi.

Features

• 19 MCP Tools: System info, CPU, memory, disk, disk I/O, network, network connections, processes, thermal, Docker, system health, service status, plus monitoring and alerting tools
• MCP Resources: Subscribable `sys://metrics/*` resources for proactive state reads
• MCP Prompts: `analyze_system_health` and `diagnose_performance_issue` prompt templates
• Streaming Metrics: Delta-based throughput sampling (network bytes/s, disk IOPS/bytes/s) and history
• Threshold Alerting: Background monitoring that generates warning/critical alerts on resource saturation
• Configurable: CLI arguments for temperature units, process limits, mount points, and interfaces
• Cross-Platform: Works on any Linux system (enhanced metrics for Raspberry Pi)
• AI-Ready: Designed for integration with Claude Desktop, Cursor, or any MCP client

Installation

Prerequisites

• Go 1.25.6 or higher
• Linux system (tested on Ubuntu, Debian, Raspberry Pi OS)

Build from Source

The project uses a `Makefile` for common tasks.

git clone 
cd sysmetrics-mcp
make build

The compiled binary will be located in `bin/sysmetrics-mcp`.

Install to PATH

# Option 1: System-wide (installs to /usr/local/bin)
sudo make install

# Option 2: User-local
mkdir -p ~/.local/bin
cp bin/sysmetrics-mcp ~/.local/bin/
# Add to PATH if not already: export PATH="$HOME/.local/bin:$PATH"

Verify Installation

sysmetrics-mcp --help

Configuration

Local AI Agents (Gemini CLI / Personal Agents)

Add to your agent's configuration file:

{
  "sysmetrics": {
    "type": "stdio",
    "command": "sysmetrics-mcp",
    "args": [
      "--temp-unit", "celsius",
      "--max-processes", "10"
    ]
  }
}

Available CLI Flags

MCP Tools

`get_system_info`

Returns system information including hostname, OS, uptime, and platform details.

`get_cpu_metrics`

Returns CPU usage, temperature, core count, and load average.

Optional Arguments:

• `temp_unit`: Override temperature unit

`get_memory_metrics`

Returns RAM and swap usage statistics with both bytes and human-readable formats.

`get_disk_metrics`

Returns disk usage for all or specified mount points.

Optional Arguments:

• `mount_points`: Comma-separated mount points to check
• `human_readable`: Include human-readable sizes (default: true)

`get_network_metrics`

Returns network interface statistics including bytes sent/received and IP addresses.

Optional Arguments:

• `interfaces`: Comma-separated interface names to check

`get_process_list`

Returns list of running processes sorted by resource usage.

Optional Arguments:

• `limit`: Maximum number of processes (1-50)
• `sort_by`: Sort by `cpu`, `memory`, or `pid` (default: `cpu`)

`get_thermal_status`

Returns thermal status including CPU/GPU temperatures and throttling information (Raspberry Pi).

Optional Arguments:

• `temp_unit`: Override temperature unit

`get_disk_io_metrics`

Returns disk I/O statistics including read/write throughput, IOPS, and I/O time per device.

Optional Arguments:

• `devices`: Comma-separated device names to check (e.g. `sda,nvme0n1`)

`get_system_health`

Returns an aggregated health dashboard with CPU, memory, disk, and uptime. Includes an overall status of `healthy`, `warning`, or `critical` based on resource thresholds.

`get_docker_metrics`

Returns Docker container metrics including CPU and memory usage via cgroups. Returns an empty list gracefully if Docker is not available.

Optional Arguments:

• `container_id`: Filter to a specific container by ID or name

`get_network_connections`

Returns active TCP/UDP network connections with local/remote addresses, status, and owning PID.

Optional Arguments:

• `kind`: Connection type filter (`tcp`, `udp`, or `all`; default: `all`)
• `status`: Filter by connection status (e.g. `LISTEN`, `ESTABLISHED`)

`get_service_status`

Returns systemd service health information via `systemctl show`.

Required Arguments:

• `services`: Comma-separated list of service names to check

`start_monitoring`

Starts background sampling of system metrics. Once running, the server retains a history buffer and evaluates resource thresholds to generate alerts.

Optional Arguments:

• `interval`: Sampling interval in seconds (defaults to `--monitor-interval`)

`stop_monitoring`

Stops background sampling.

`get_monitoring_status`

Returns whether monitoring is running, the aggregate health status, and the latest snapshot.

`get_metrics_history`

Returns recent metric snapshots captured by the monitor.

Optional Arguments:

• `seconds`: Only return snapshots captured within the last N seconds

`get_alerts`

Returns threshold alerts generated since the last read (read-then-drain).

Optional Arguments:

• `severity`: Filter by `warning` or `critical`

`get_network_throughput`

Returns per-interface network throughput rates (bytes/sec) since the last sample.

`get_disk_throughput`

Returns per-device disk I/O throughput rates (bytes/sec and IOPS) since the last sample.

MCP Resources

The server exposes subscribable resources under the `sys://metrics/*` namespace so clients can read current state without issuing a tool call:

MCP Prompts

• `analyze_system_health` — gathers and summarizes overall system health.
• `diagnose_performance_issue` — diagnoses a reported performance problem by checking CPU, memory, disk, network, and top processes.

Example Usage

Once configured, you can ask your AI assistant:

• "What's my CPU temperature?"
• "Show me disk usage for / and /home"
• "List the top 5 processes by memory usage"
• "What's my network usage on eth0?"
• "Check if my Raspberry Pi is throttling"
• "What's the overall health of my system?"
• "Show me active TCP connections in LISTEN state"
• "Check if the SSH and Docker services are running"
• "What are the disk I/O stats for my drives?"
• "How much CPU and memory are my Docker containers using?"
• "Start monitoring every 2 seconds and alert me if CPU is high"
• "Show me disk throughput over the last minute"
• "Are there any recent resource warnings?"

Raspberry Pi Enhancements

On Raspberry Pi systems, the server provides additional metrics:

• CPU Temperature: Reads from `/sys/class/thermal/thermal_zone0/temp`
• GPU Temperature: Uses `vcgencmd measure_temp`
• Throttling Status: Uses `vcgencmd get_throttled` to detect:
  • Under-voltage conditions
  • Frequency capping
  • Thermal throttling
  • Soft temperature limits

On non-Pi systems, these metrics return `"not_available"` gracefully.

Development

Use the included `Makefile` for development tasks:

# Run tests
make test

# Run linter (go vet)
make lint

# Clean build artifacts
make clean

# Download and tidy dependencies
make deps

Requirements

• Go 1.25.6+
• Linux system
• For Pi features: Raspberry Pi OS with `vcgencmd` available

License

MIT