System Metrics MCP

System Metrics MCP is a Python-based Model Context Protocol server that exposes system health, process information, disk details, network statistics, battery status, temperature sensors, and secure log file access.

Installation

1. Install Python 3.11 or newer.

2. Create and activate a virtual environment:

python -m venv .venv
.\.venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

Running the Server

From the project root:

python server.py

This starts the MCP server using stdio transport, which is compatible with Claude Desktop and other MCP clients.

Claude Desktop Configuration

Use the following `claude.json` or equivalent configuration block:

{
  "mcpServers": {
    "system-metrics": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}

Available Tools

• `get_system_status()`
• `list_high_cpu_processes(limit=5)`
• `list_high_memory_processes(limit=5)`
• `get_disk_details()`
• `read_log_file(filename)`
• `get_network_stats()`
• `get_battery_status()`
• `get_top_process_details(pid)`
• `get_system_temperature()`

Important Security Notes

• `read_log_file` only allows files inside the local `./logs/` directory.
• Absolute paths and path traversal attempts are rejected.
• Log files larger than 1 MB are refused to prevent denial-of-service or memory exhaustion.
• MCP tool inputs are validated using FastMCP strict input validation.

Example Prompts

• "What is the current CPU and RAM usage on the system?"
• "List the top 5 processes by CPU usage."
• "Show the top 5 memory-hungry processes."
• "Return the current disk utilization details."
• "Read the contents of `app.log` from the logs directory."
• "Provide the system network statistics."
• "What is the battery charge percentage and is the system plugged in?"
• "Give me detailed metrics for PID 1234."
• "Do we have temperature sensors available and what are their readings?"

Security Design

• Log files can only be read from the local `./logs/` directory.
• Absolute file paths are rejected.
• Path traversal attempts such as `../` or `../../` are blocked using `pathlib.Path.resolve()` and strict directory validation.
• Invalid file access attempts are logged and returned as human-readable errors.
• Each tool implements exception handling for `FileNotFoundError`, `PermissionError`, `psutil.AccessDenied`, `psutil.NoSuchProcess`, and unexpected exceptions.

Logging

Application logging is written to `logs/server.log` and also streamed to the console. The server logs:

• tool invocations
• access errors
• unexpected failures

Notes

• The server is designed for production-quality usage with async support and modular implementation.
• The `logs/` directory is intentionally included as an empty folder for secure log access and server logging.