# 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:

```text
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

| Technology        | Purpose                    |
| ----------------- | -------------------------- |
| TypeScript        | Main programming language  |
| Node.js           | Runtime                    |
| MCP SDK           | Build MCP server           |
| systeminformation | Collect system information |
| Express           | HTTP server                |
| Streamable HTTP   | HTTP MCP transport         |
| stdio             | Local MCP transport        |
| Codex CLI         | MCP client                 |
| npm               | Package management         |

---

# 📁 Project Structure

```text
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:

```text
http://localhost:3000/mcp
```

### `src/stdio.ts`

stdio-based MCP server used by local Codex.

The stdio architecture is:

```text
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:

```bash
git clone <your-repository-url>
```

Enter the project:

```bash
cd system-monitor-mcp
```

Install dependencies:

```bash
npm install
```

---

# ▶️ Running the HTTP MCP Server

Start the development server:

```bash
npm run dev
```

The server should start at:

```text
http://localhost:3000
```

You can test the root endpoint:

```bash
curl http://localhost:3000
```

Expected response:

```text
System Monitor MCP Server is running
```

---

# 🔌 MCP HTTP Endpoint

The MCP endpoint is:

```text
POST http://localhost:3000/mcp
```

The server uses:

```typescript
StreamableHTTPServerTransport;
```

for HTTP MCP communication.

---

# 🖥️ Local Codex Integration

For local Codex, the project uses the **stdio transport**.

Configure Codex with:

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

Check the configuration:

```bash
codex mcp get system-monitor
```

Expected:

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

List MCP servers:

```bash
codex mcp list
```

---

# 🧪 Testing the MCP

Start Codex:

```bash
codex
```

Then ask:

```text
Call my_custom_mcp_test from my system-monitor MCP.
```

The MCP should return:

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

This confirms that the custom MCP server is being accessed.

---

# 🔧 Current MCP Tools

## `get_memory_usage`

Returns current RAM and Swap information.

Example response:

```json
{
  "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:

```text
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:

```text
get_cpu_usage
get_memory_usage
get_disk_usage
get_system_info
```

---

## Phase 2 — Process Monitoring

Implement:

```text
list_processes
get_process
```

Example:

```text
Top 10 processes by CPU usage
```

or:

```text
Top 10 processes by memory usage
```

---

## Phase 3 — System Health

Create:

```text
get_system_health
```

It should analyze:

```text
CPU
RAM
Swap
Disk
Load Average
Processes
```

and return:

```text
Healthy
Warning
Critical
```

Example:

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

---

# 🤖 Advanced Diagnosis

Create:

```text
diagnose_system
```

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

Example:

```text
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:

```text
get_network_stats
get_network_connections
```

Possible information:

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

---

# 🌡️ Hardware Monitoring

Planned:

```text
get_temperature
get_sensors
```

Possible information:

```text
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:

```text
CPU
RAM
Swap
Disk
Load Average
```

Potential storage:

```text
SQLite
```

Then implement:

```text
get_metric_history
```

Example:

```text
Show me RAM usage during the last hour.
```

---

# 🚨 Alerts

Add configurable thresholds.

Example:

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

Tool:

```text
check_alerts
```

Example:

```text
⚠️ Disk usage is 91%.

Critical threshold: 90%
```

---

# ⚙️ Background Monitoring

Eventually the MCP can continuously collect metrics.

```text
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:

```text
execute_shell_command
```

Instead use specific, validated operations:

```text
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:

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

### MCP Integration Tests

Test:

```text
initialize
tools/list
tools/call
```

Both transports should be tested:

```text
stdio
Streamable HTTP
```

---

# 🐳 Docker

A future version can support Docker for the HTTP server.

Possible architecture:

```text
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:

```text
                         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:

```text
What is my current CPU usage?
```

```text
How much RAM am I using?
```

```text
Which process is using the most memory?
```

```text
How much disk space is left?
```

```text
Is my system healthy?
```

```text
Why is my laptop slow?
```

```text
Show me the system's network statistics.
```

```text
Show me the most CPU-intensive processes.
```

```text
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

- [x] MCP server setup
- [x] TypeScript configuration
- [x] Streamable HTTP server
- [x] stdio server
- [x] MCP initialization
- [x] Tool discovery
- [x] Memory monitoring
- [x] Custom MCP verification
- [x] 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:

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

---

## 📄 License

Add a license before publishing the project publicly.

For example:

```text
MIT License
```