System Monitor MCP

A Model Context Protocol (MCP) server built with TypeScript and Node.js that allows AI clients such as Codex to access real-time system information from a Linux machine.

The project is designed to start as a beginner-friendly MCP and gradually evolve into an intermediate/advanced system monitoring agent.

🚀 Features

Currently Implemented (through Phase 7)

• ✅ MCP server using the official MCP SDK

• ✅ Streamable HTTP transport

• ✅ stdio transport for local Codex

• ✅ RAM and Swap monitoring

• ✅ CPU, load average, and per-core monitoring

• ✅ Disk/filesystem monitoring

• ✅ Process listing and process details

• ✅ System information and uptime

• ✅ Health scoring and system diagnosis

• ✅ Network interfaces, traffic, and active connections

• ✅ Automated TypeScript/MCP tests

• ✅ Local Codex integration

• ✅ TypeScript support

• ✅ systeminformation integration

Planned Features (Phase 8+)

• ⏳ Temperature/sensor monitoring

• ⏳ Historical metrics

• ⏳ Alerts and thresholds

• ⏳ Background monitoring

• ⏳ Service monitoring

• ⏳ Safe process management

• ⏳ Authentication and authorization

• ⏳ Automated tests

• ⏳ Docker deployment

🧠 What is MCP?

Model Context Protocol (MCP) is a protocol that allows AI applications to interact with external tools and data sources.

Instead of an AI model only answering from its existing knowledge, an MCP server can give it access to real information.

For this project:

User
  ↓
AI Client / Codex
  ↓
MCP
  ↓
System Monitor MCP
  ↓
Linux System
  ↓
CPU / RAM / Disk / Processes

For example, you can ask:

What is my current RAM usage?

The AI can call the MCP tool and receive the actual RAM information from your machine.

🛠️ Tech Stack

📁 Project Structure

system-monitor-mcp/
│
├── src/
│   ├── index.ts
│   └── stdio.ts
│
├── dist/
│
├── node_modules/
│
├── package.json
├── package-lock.json
├── tsconfig.json
├── project-plan.md
├── README.md
└── .gitignore

src/index.ts

HTTP-based MCP server.

It exposes:

http://localhost:3000/mcp

src/stdio.ts

stdio-based MCP server used by local Codex.

The stdio architecture is:

Codex
  ↓
stdio
  ↓
stdio.ts
  ↓
MCP Server

project-plan.md

Contains the roadmap for turning this project into an intermediate/advanced monitoring system.

📦 Installation

Clone the repository:

git clone <your-repository-url>

Enter the project:

cd system-monitor-mcp

Install dependencies:

npm install

▶️ Running the HTTP MCP Server

Start the development server:

npm run dev

The server should start at:

http://localhost:3000

You can test the root endpoint:

curl http://localhost:3000

Expected response:

System Monitor MCP Server is running

🔌 MCP HTTP Endpoint

The MCP endpoint is:

POST http://localhost:3000/mcp

The server uses:

StreamableHTTPServerTransport;

for HTTP MCP communication.

🖥️ Local Codex Integration

For local Codex, the project uses the stdio transport.

Configure Codex with:

codex mcp add system-monitor -- npx tsx "/home/rakesh/Next js/system-monitor-mcp/src/stdio.ts"

Check the configuration:

codex mcp get system-monitor

Expected:

system-monitor
  enabled: true
  transport: stdio
  command: npx
  args: tsx /home/rakesh/Next js/system-monitor-mcp/src/stdio.ts

List MCP servers:

codex mcp list

🧪 Testing the MCP

Start Codex:

codex

Then ask:

Call my_custom_mcp_test from my system-monitor MCP.

The MCP should return:

SUCCESS! This response came from Rakesh's custom System Monitor MCP.

This confirms that the custom MCP server is being accessed.

🔧 Current MCP Tools

Related MCP server: mcp-remote-agent

get_memory_usage

Returns current RAM and Swap information.

Example response:

{
  "ram": {
    "total": 6100000000,
    "used": 4300000000,
    "free": 1800000000,
    "available": 2000000000
  },
  "swap": {
    "total": 4500000000,
    "used": 2600000000,
    "free": 1900000000
  }
}

my_custom_mcp_test

A simple test tool used to verify that the AI client is actually calling the custom MCP server.

Response:

SUCCESS! This response came from Rakesh's custom System Monitor MCP.

This tool is mainly for development/testing and can be removed later.

🗺️ Development Roadmap

Phase 1 — Basic Monitoring

Implement:

get_cpu_usage
get_memory_usage
get_disk_usage
get_system_info

Phase 2 — Process Monitoring

Implement:

list_processes
get_process

Example:

Top 10 processes by CPU usage

or:

Top 10 processes by memory usage

Phase 3 — System Health

Create:

get_system_health

It should analyze:

CPU
RAM
Swap
Disk
Load Average
Processes

and return:

Healthy
Warning
Critical

Example:

{
  "score": 78,
  "status": "warning",
  "issues": [
    {
      "type": "memory",
      "severity": "medium",
      "message": "Memory usage is high."
    }
  ]
}

🤖 Advanced Diagnosis

Create:

diagnose_system

The tool will collect multiple metrics and help the AI understand why the system might be slow.

Example:

CPU: 22%
RAM: 89%
Swap: 63%
Disk: 81%

Diagnosis:

The system is experiencing memory pressure.
Several applications are consuming significant memory.

🌐 Network Monitoring

Planned tools:

get_network_stats
get_network_connections

Possible information:

Network interfaces
IP addresses
Upload traffic
Download traffic
Received bytes
Transmitted bytes
Active connections

🌡️ Hardware Monitoring

Planned:

get_temperature
get_sensors

Possible information:

CPU temperature
GPU temperature
Fan speed
Other available sensors

Hardware support will depend on the operating system and machine.

📊 Historical Monitoring

Instead of only returning the current state, the MCP can store metrics.

Example:

CPU
RAM
Swap
Disk
Load Average

Potential storage:

SQLite

Then implement:

get_metric_history

Example:

Show me RAM usage during the last hour.

🚨 Alerts

Add configurable thresholds.

Example:

{
  "cpu": {
    "warning": 70,
    "critical": 90
  },
  "memory": {
    "warning": 75,
    "critical": 90
  },
  "disk": {
    "warning": 75,
    "critical": 90
  }
}

Tool:

check_alerts

Example:

⚠️ Disk usage is 91%.

Critical threshold: 90%

⚙️ Background Monitoring

Eventually the MCP can continuously collect metrics.

Background Worker
       ↓
Collect metrics
       ↓
Store metrics
       ↓
Check thresholds
       ↓
Generate alerts

The monitoring interval should be configurable.

🔐 Security

Advanced system-management features should be implemented carefully.

Avoid creating a generic tool such as:

execute_shell_command

Instead use specific, validated operations:

kill_process
restart_service

Potential security controls:

• Input validation

• Authorization

• User confirmation

• Audit logging

• Rate limiting

• Least-privilege permissions

• Authentication for remote clients

• HTTPS for remote deployment

🧪 Testing Strategy

The project should eventually include:

Unit Tests

Test:

CPU calculations
Memory calculations
Disk thresholds
Health scoring
Alert generation
Input validation

MCP Integration Tests

Test:

initialize
tools/list
tools/call

Both transports should be tested:

stdio
Streamable HTTP

🐳 Docker

A future version can support Docker for the HTTP server.

Possible architecture:

Client
   ↓
HTTPS
   ↓
Reverse Proxy
   ↓
MCP Container

However, monitoring the host machine from inside a container requires additional Linux permissions and host integration.

The native Ubuntu version should be completed first.

📈 Final Architecture

The long-term architecture is:

                         AI CLIENT
                            │
                 ┌──────────┴──────────┐
                 │                     │
              Codex CLI            HTTP Client
                 │                     │
               stdio               HTTPS/HTTP
                 │                     │
                 └──────────┬──────────┘
                            │
                       MCP Server
                            │
                    ┌───────┴───────┐
                    │               │
                Tool Layer      Transport
                    │          stdio / HTTP
                    │
        ┌───────────┼───────────────┐
        │           │               │
       CPU         RAM             Disk
        │           │               │
        └───────────┼───────────────┘
                    │
              Service Layer
                    │
        ┌───────────┼────────────┐
        │           │            │
     Process     Network       Health
     Service     Service       Service
                                  │
                              Diagnosis
                                  │
                              Alerts
                                  │
                              History
                                  │
                              SQLite

🎯 Learning Objectives

By completing this project, you will gain practical experience with:

MCP

• MCP architecture

• MCP tools

• Tool schemas

• stdio transport

• Streamable HTTP

• MCP client integration

TypeScript

• Async/await

• Types and interfaces

• Modules

• Error handling

• Schema validation

Node.js

• Streams

• Processes

• Signals

• File system

• Background workers

Linux

• CPU monitoring

• Memory and Swap

• Processes

• Disk/filesystems

• Network interfaces

• systemd

• Permissions

Backend Engineering

• HTTP APIs

• Authentication

• Authorization

• Logging

• Testing

• Docker

• Production deployment

💡 Example Use Cases

Once completed, you should be able to ask an AI client:

What is my current CPU usage?

How much RAM am I using?

Which process is using the most memory?

How much disk space is left?

Is my system healthy?

Why is my laptop slow?

Show me the system's network statistics.

Show me the most CPU-intensive processes.

What system problems occurred during the last hour?

🏆 Portfolio Description

System Monitor MCP is a TypeScript/Node.js based Model Context Protocol server that gives AI clients access to real-time Linux system information. The project provides monitoring capabilities for CPU, memory, disk, processes, network, system health, alerts, and historical metrics, with support for local Codex integration through stdio and remote clients through Streamable HTTP.

📌 Project Status

Current status: 🚧 In Development

Completed

• MCP server setup

• TypeScript configuration

• Streamable HTTP server

• stdio server

• MCP initialization

• Tool discovery

• Memory monitoring

• Custom MCP verification

• Codex MCP configuration

Next

• CPU monitoring

• Disk monitoring

• System information

• Process monitoring

• System health

• Diagnosis

• Network monitoring

• Historical metrics

• Alerts

• Background monitoring

• Safe management tools

• Security

• Testing

• Docker

• Production deployment

👨‍💻 Author

Rakesh Molla

Built as a practical project for learning:

MCP + TypeScript + Node.js + Linux + AI Agents

📄 License

Add a license before publishing the project publicly.

For example:

MIT License