mcp-system-monitor

MCP System Monitor Server

A cross-platform MCP (Model Context Protocol) server that provides comprehensive real-time system monitoring capabilities for LLMs. Built with FastMCP for easy integration with Claude Desktop and other MCP-compatible clients.

Features

System Monitoring

• CPU Monitoring: Real-time usage, per-core statistics, frequency, temperature, detailed processor information (model, vendor, architecture, cache sizes)
• GPU Monitoring: Multi-vendor GPU support (NVIDIA with full metrics, Apple Silicon with comprehensive support including unified memory and core count, AMD/Intel with basic info)
• Memory Monitoring: RAM and swap usage, availability statistics
• Disk Monitoring: Space usage, filesystem information for all mounted drives
• Network Statistics: Interface-level traffic and error counters
• Process Monitoring: Top processes by CPU/memory usage
• System Information: OS details, hostname, uptime, architecture

MCP Tools Available

• get_current_time: Get the current local time in ISO format
• get_cpu_info: Get current CPU usage and statistics
• get_gpu_info: Get GPU information for all detected GPUs
• get_memory_info: Get RAM and swap usage
• get_disk_info: Get disk usage for all mounted drives
• get_system_snapshot: Get complete system state in one call
• monitor_cpu_usage: Monitor CPU usage over a specified duration
• get_top_processes: Get top processes by CPU or memory usage
• get_network_stats: Get network interface statistics

MCP Resources

• system://live/cpu: Live CPU usage data
• system://live/memory: Live memory usage data
• system://config: System configuration and hardware information

GPU Support Details

NVIDIA GPUs:

• Full metrics: usage percentage, memory (used/total), temperature, power consumption
• Supports multiple NVIDIA GPUs
• Requires NVIDIA drivers and NVML libraries

Apple Silicon GPUs:

• Comprehensive support for M1, M2, and M3 chips
• GPU core count detection
• Unified memory reporting (shares system RAM)
• Metal API support detection
• Temperature monitoring (when available)

AMD/Intel GPUs:

• Basic detection and identification
• Limited metrics depending on platform and drivers

Requirements

• Python 3.10+
• Windows, macOS, or Linux
• GPU (optional): NVIDIA GPUs for full metrics, Apple Silicon GPUs fully supported on macOS

Installation

From GitHub

1. Clone the repository:

   git clone https://github.com/huhabla/mcp-system-monitor.git
   cd mcp-system-monitor
   

2. Install dependencies using uv (recommended):

   uv pip install -e .
   

   Or using pip:

   pip install -e .
   

Optional Dependencies

For Windows-specific features:

pip install mcp-system-monitor[win32]

Usage

Development Mode

Test the server with the MCP Inspector:

uv run mcp dev mcp_system_monitor_server.py

Claude Desktop Integration

Install the server in Claude Desktop:

uv run mcp install mcp_system_monitor_server.py --name "System Monitor"

Direct Execution

Run the server directly:

python mcp_system_monitor_server.py

MCP Servers Json Config

Modify the following JSON template to set the path to the MCP server in your MCP client for Windows:

{
  "mcpServers": {
    "mpc-system-monitor": {
      "command": "cmd",
      "args": [
        "/c",
        "C:/Users/Sören Gebbert/Documents/GitHub/mcp-system-monitor/start_mpc_system_monitor.bat"
      ]
    }
  }
}

Modify the following JSON template to set the path to the MCP server in your MCP client for MacOS:

{
  "mcpServers": {
    "mpc-system-monitor": {
      "command": "/bin/zsh",
      "args": [
        "/Users/holistech/Documents/GitHub/mcp-system-monitor/start_mcp_system_monitor.sh"
      ]
    }
  }
}

Example Tool Usage

Once connected to Claude Desktop or another MCP client, you can use natural language to interact with the system monitor:

• "Show me the current CPU usage"
• "What's my GPU temperature?"
• "How many GPU cores does my Apple M1 Max have?"
• "Show me GPU memory usage and whether it's unified memory"
• "How much disk space is available?"
• "Monitor CPU usage for the next 10 seconds"
• "Show me the top 5 processes by memory usage"
• "Get a complete system snapshot"

Architecture

The server uses a modular collector-based architecture:

• BaseCollector: Abstract base class providing caching and async data collection
• Specialized Collectors: CPU, GPU, Memory, Disk, Network, Process, and System collectors
• Pydantic Models: Type-safe data models for all system information
• FastMCP Integration: Simple decorators for exposing tools and resources

Caching Strategy

All collectors implement intelligent caching to:

• Reduce system overhead from frequent polling
• Provide consistent data within time windows
• Allow configurable cache expiration

Testing

Run the test suite:

pytest tests/test_mcp_system_monitor_server.py -v

Run with coverage:

pytest tests/test_mcp_system_monitor_server.py --cov=mcp_system_monitor_server --cov-report=html

Platform Support

⚠️ = Limited support, depends on hardware/drivers

Troubleshooting

GPU Monitoring Not Working

NVIDIA GPUs:

• Ensure NVIDIA drivers are installed
• Check if nvidia-smi command works
• The server will gracefully handle missing GPU libraries

Apple Silicon GPUs:

• Supported on macOS with M1, M2, and M3 chips
• Provides comprehensive information including unified memory and GPU core count
• Uses system_profiler command (available by default on macOS)

Permission Errors

• Some system information may require elevated privileges
• The server handles permission errors gracefully and skips inaccessible resources

High CPU Usage

• Adjust the monitoring frequency by modifying collector update intervals
• Use cached data methods to reduce system calls
• Default cache expiration is 2 seconds for most collectors
• Consider increasing max_age parameter in get_cached_data() calls for less frequent updates

Performance Considerations

• The server uses intelligent caching to minimize system calls
• Each collector maintains its own cache with configurable expiration
• Continuous monitoring tools (like monitor_cpu_usage) bypass caching for real-time data
• For high-frequency polling, consider using the resource endpoints which leverage caching

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with FastMCP
• System monitoring via psutil
• NVIDIA GPU support via nvidia-ml-py