MCP System Monitor Server for Linux

A Model Context Protocol (MCP) server implementation designed for AI agents to monitor and interact with Linux servers (Ubuntu, CentOS, RedHat, etc.). This server provides comprehensive system information including CPU, memory, disk, network, and process data through both MCP protocol and HTTP REST API, enabling AI agents to perform remote system monitoring and management tasks.

Development Platform

This project was developed and integrated using Claude Code Max, an advanced AI-powered development platform. The entire codebase, architecture design, testing, and documentation were created with Claude Code Max's assistance, making it a comprehensive AI-assisted development project.

Author

Name: Thinh Nguyen
Role: Enterprise IT
Email: hello@boringlab.info

Repository

Official GitHub: https://github.com/hungtrungthinh/mcp-system-monitor

Table of Contents

• Features
• Architecture
• Installation
• Quick Start
• API Documentation
• MCP Protocol
• Data Structures
• Development
• Deployment
• Use Cases
• Roadmap

Features

• AI-Assisted Development: Built entirely with Claude Code Max, demonstrating advanced AI-powered software development capabilities
• Linux Server Support: Optimized for Ubuntu, CentOS, RedHat, and other Linux distributions
• AI Agent Integration: Designed for AI agents to perform remote system monitoring and management
• Real System Data: Collects actual system information from Linux procfs and system commands
• System Information: Hostname, OS details, kernel version, uptime
• CPU Monitoring: Usage percentage, frequency, core count, brand information, temperature
• Memory Monitoring: RAM and swap usage, available memory from /proc/meminfo
• Disk Monitoring: Storage usage, file system information, mount points from df command
• Network Monitoring: Interface statistics, traffic data, error counts from /proc/net/dev
• Process Management: Process list, individual process details, resource usage from ps command
• Real-time Metrics: Comprehensive system metrics collection
• HTTP REST API: Easy integration for AI agents and web applications
• MCP Protocol: Standard Model Context Protocol support for AI agent communication

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   HTTP Client   │    │   MCP Client    │    │   Other Tools   │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │     HTTP Server           │
                    │   (Port 8080)             │
                    │   (Axum Framework)        │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │     MCP Server            │
                    │  (JSON-RPC Handler)       │
                    │  (Protocol Implementation)│
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │   System Monitor          │
                    │  (Core Monitoring Logic)  │
                    │  (sysinfo integration)    │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │   Linux System Layer      │
                    │  (procfs, sysfs, commands)│
                    │  (CPU, Memory, Disk, etc.)│
                    └───────────────────────────┘

Installation

Prerequisites

• Linux Server: Ubuntu 18.04+, CentOS 7+, RedHat 7+, or compatible distribution
• System Tools: Standard Linux commands (ps, df, ip, cat, hostname, uname)
• Rust: 1.70 or higher
• Cargo: Package manager
• Quick Start

System Requirements

• Minimum: 512MB RAM, 1 CPU core
• Recommended: 1GB RAM, 2 CPU cores
• Storage: 100MB for application + logs
• Network: HTTP/HTTPS access on port 8080

Build and Run

1. Clone the repository:

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

2. Build the project:

# Development build
cargo build

# Production build
cargo build --release

3. Run the server:

# Development mode
cargo run

# Production mode
cargo run --release

The server will start on port 8080 by default.

Quick Start

1. Start the Server

# Clone and build
git clone https://github.com/hungtrungthinh/mcp-system-monitor.git
cd mcp-system-monitor
cargo build --release

# Run the server
cargo run --release

2. Test the API

# Health check
curl http://localhost:8080/health

# Get system information
curl http://localhost:8080/api/system/info

# Get CPU information
curl http://localhost:8080/api/system/cpu

3. Run the Example Client

# In another terminal
cargo run --example client

API Documentation

Base URL

http://localhost:8080

Authentication

Currently, no authentication is required. For production use, implement appropriate authentication mechanisms.

Response Format

All API responses are in JSON format with the following structure:

{
  "jsonrpc": "2.0",
  "id": "request-id",
  "result": { ... },
  "error": null
}

HTTP REST API Endpoints

System Information

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "service": "MCP System Monitor",
  "timestamp": "2024-01-01T00:00:00Z"
}

GET /api/system/info

Get comprehensive system information.

Response:

{
  "hostname": "server.example.com",
  "os_name": "Ubuntu",
  "os_version": "20.04.3 LTS",
  "kernel_version": "5.4.0-74-generic",
  "uptime": 86400,
  "boot_time": "2024-01-01T00:00:00Z"
}

GET /api/system/cpu

Get CPU information and usage statistics.

Response:

{
  "name": "Intel(R) Core(TM) i7-8700K",
  "brand": "GenuineIntel",
  "frequency": 3600,
  "cores": 6,
  "usage_percent": 45.2,
  "temperature": 65.5
}

GET /api/system/memory

Get memory information including RAM and swap usage.

Response:

{
  "total": 16777216000,
  "used": 8388608000,
  "free": 8388608000,
  "available": 12582912000,
  "swap_total": 2147483648,
  "swap_used": 0,
  "swap_free": 2147483648,
  "usage_percent": 50.0,
  "swap_usage_percent": 0.0
}

GET /api/system/disks

Get disk information for all mounted filesystems.

Response:

[
  {
    "name": "/dev/sda1",
    "mount_point": "/",
    "file_system": "ext4",
    "total_space": 107374182400,
    "used_space": 53687091200,
    "free_space": 53687091200,
    "usage_percent": 50.0
  }
]

GET /api/system/networks

Get network interface information and statistics.

Response:

[
  {
    "interface": "eth0",
    "ip_address": "192.168.1.100",
    "mac_address": "00:11:22:33:44:55",
    "bytes_received": 1073741824,
    "bytes_transmitted": 536870912,
    "packets_received": 1000000,
    "packets_transmitted": 500000,
    "errors_received": 0,
    "errors_transmitted": 0
  }
]

GET /api/system/processes

Get information about all running processes.

Response:

[
  {
    "pid": 1,
    "name": "systemd",
    "command": "/sbin/init",
    "cpu_usage": 0.1,
    "memory_usage": 1048576,
    "memory_usage_percent": 0.01,
    "status": "S",
    "start_time": "2024-01-01T00:00:00Z",
    "user": "root",
    "priority": 0
  }
]

GET /api/system/processes/{pid}

Get information about a specific process by PID.

Parameters:

• pid (path): Process ID

Response:

{
  "pid": 1234,
  "name": "nginx",
  "command": "nginx: master process",
  "cpu_usage": 0.5,
  "memory_usage": 2097152,
  "memory_usage_percent": 0.02,
  "status": "S",
  "start_time": "2024-01-01T00:00:00Z",
  "user": "www-data",
  "priority": 0
}

GET /api/system/metrics

Get complete system metrics snapshot.

Response:

{
  "timestamp": "2024-01-01T00:00:00Z",
  "system_info": { ... },
  "cpu_info": { ... },
  "memory_info": { ... },
  "disks": [ ... ],
  "networks": [ ... ],
  "processes": [ ... ]
}

Monitoring Control

POST /api/monitoring/start

Start continuous monitoring.

Response:

{
  "started": true,
  "message": "Monitoring started successfully"
}

POST /api/monitoring/stop

Stop continuous monitoring.

Response:

{
  "stopped": true,
  "message": "Monitoring stopped successfully"
}

GET /api/monitoring/status

Get monitoring status.

Response:

{
  "monitoring_active": true,
  "last_update": "2024-01-01T00:00:00Z",
  "service_status": "running"
}

Example API Usage

Using curl

# Get system information
curl http://localhost:8080/api/system/info

# Get CPU usage and temperature
curl http://localhost:8080/api/system/cpu

# Get memory information
curl http://localhost:8080/api/system/memory

# Get disk usage
curl http://localhost:8080/api/system/disks

# Get network interfaces
curl http://localhost:8080/api/system/networks

# Get top processes by CPU usage
curl http://localhost:8080/api/system/processes

# Get specific process details
curl http://localhost:8080/api/system/processes/1234

# Get complete system metrics
curl http://localhost:8080/api/system/metrics

# Start continuous monitoring
curl -X POST http://localhost:8080/api/monitoring/start

# Stop monitoring
curl -X POST http://localhost:8080/api/monitoring/stop

Using Python

import requests

base_url = "http://localhost:8080"

# Get system info
response = requests.get(f"{base_url}/api/system/info")
system_info = response.json()

# Get CPU info
response = requests.get(f"{base_url}/api/system/cpu")
cpu_info = response.json()

# Get processes
response = requests.get(f"{base_url}/api/system/processes")
processes = response.json()

Using JavaScript/Node.js

const axios = require('axios');

const baseUrl = 'http://localhost:8080';

// Get system info
const systemInfo = await axios.get(`${baseUrl}/api/system/info`);

// Get CPU info
const cpuInfo = await axios.get(`${baseUrl}/api/system/cpu`);

// Get processes
const processes = await axios.get(`${baseUrl}/api/system/processes`);

MCP Protocol

The server implements the Model Context Protocol for system monitoring using JSON-RPC 2.0.

Available Methods

• getSystemInfo - Get system information
• getCPUInfo - Get CPU information
• getMemoryInfo - Get memory information
• getDiskInfo - Get disk information
• getNetworkInfo - Get network information
• getProcesses - Get all processes
• getProcessByPID - Get specific process by PID
• getSystemMetrics - Get complete system metrics
• startMonitoring - Start monitoring
• stopMonitoring - Stop monitoring

Example MCP Request

{
  "jsonrpc": "2.0",
  "id": "123",
  "method": "getSystemInfo",
  "params": {}
}

Example MCP Response

{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "hostname": "server.example.com",
    "os_name": "Ubuntu",
    "os_version": "20.04.3 LTS",
    "kernel_version": "5.4.0-74-generic",
    "uptime": 86400,
    "boot_time": "2024-01-01T00:00:00Z"
  },
  "error": null
}

Error Response

{
  "jsonrpc": "2.0",
  "id": "123",
  "result": null,
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": null
  }
}