System Health MCP Server

A Model Context Protocol (MCP) server that provides real-time system health monitoring capabilities including CPU load, memory usage, and battery status.

Features

• Real-time CPU monitoring: Get current CPU load percentage
• Memory statistics: Track active and total memory usage
• Battery information: Monitor battery level and charging status
• Hardware details: GPU, network interfaces, disk usage, and Docker containers

Prerequisites

• Node.js (v18 or higher recommended)
• TypeScript
• npm or yarn

Installation (from npm)

You can install and run this MCP server directly from npm:

npm install -g system-health-mcp

Then run the server:

system-health-mcp

Or, if you want to use it locally in a project:

npm install system-health-mcp

Then run:

npx system-health-mcp

You do not need to clone the repository if installing from npm.

Installation (from source)

git clone cd system-health-mcp

git clone https://github.com/jvdub/system-health-mcp.git
cd system-health-mcp
npm install
npx tsc

Configuration

To use this MCP server with an MCP-compatible client (like Claude Desktop), add the following configuration to your client's MCP settings file:

If installed globally from npm:

{
  "mcpServers": {
    "system-health": {
      "command": "system-health-mcp"
    }
  }
}

If installed locally in a project:

{
  "mcpServers": {
    "system-health": {
      "command": "npx",
      "args": ["system-health-mcp"]
    }
  }
}

If running from source:

{
  "mcpServers": {
    "system-health": {
      "command": "node",
      "args": ["/path/to/your/project/index.js"]
    }
  }
}

Important: For the source install, replace /path/to/your/project/index.js with the absolute path to the built index.js file in your cloned repository.

Example Configuration Locations

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Claude Desktop (Linux): ~/.config/Claude/claude_desktop_config.json

After updating the configuration, restart your MCP client for the changes to take effect.

Usage

This MCP server exposes two tools for comprehensive system monitoring.

Running the Server

node index.js

The server communicates via stdio and is designed to be used with MCP-compatible clients.

Tool: get_system_stats

Returns real-time system health information.

Response:

• cpuLoadPercentage: Current CPU load as a percentage
• memoryUsedGB: Active memory in gigabytes
• memoryTotalGB: Total system memory in gigabytes
• batteryLevel: Battery percentage (or "No battery" if not applicable)
• isCharging: Boolean indicating if the battery is currently charging

Example Response:

{
  "cpuLoadPercentage": "23.45",
  "memoryUsedGB": "8.42",
  "memoryTotalGB": "16.00",
  "batteryLevel": "85%",
  "isCharging": false
}

Tool: get_hardware_details

Returns detailed hardware information based on the specified category.

Parameters:

• category (required): One of "graphics", "network", "disks", or "docker"

Categories:

• graphics: GPU and graphics card information
• network: Network interface configurations
• disks: Disk usage and filesystem information
• docker: Docker container details

Example Request:

{
  "category": "graphics"
}

Development

Project Structure

• index.ts: Main server implementation
• package.json: Project dependencies and configuration
• tsconfig.json: TypeScript compiler configuration

Building

npx tsc

Type Checking

npx tsc --noEmit

Dependencies

• @modelcontextprotocol/sdk: MCP SDK for building servers
• systeminformation: Cross-platform system information library

License

ISC