sysmetrics-mcp

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 <repository>
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

Flag	Default	Description
--temp-unit	celsius	Temperature unit: celsius, fahrenheit, or kelvin
--max-processes	10	Default maximum processes to list (1-50)
--mount-points	""	Comma-separated mount points (empty = all)
--interfaces	""	Comma-separated interfaces (empty = all, excludes lo)
--enable-gpu	true	Attempt to read GPU metrics (Raspberry Pi only)
--monitor-interval	5	Default sampling interval in seconds for monitoring (1-60)

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:

URI	Description
sys://metrics/overview	Aggregated health dashboard
sys://metrics/cpu	CPU model, cores, temperature
sys://metrics/memory	RAM usage
sys://metrics/disk	Disk usage across mount points
sys://metrics/network	Network interface throughput
sys://metrics/processes/top	Template: top N processes (e.g. sys://metrics/processes/top?limit=10)

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