Terminal Monitor

License: MIT npm version

Production-ready Model Context Protocol (MCP) Server for system monitoring. Provides AI agents with real-time access to Docker containers, system resources, ports, and logs.

🚀 Quick Start

npx mcp-terminal-monitor

Or install globally:

npm install -g mcp-terminal-monitor
mcp-terminal-monitor

📋 Available Tools

Tool	Description
list_docker_containers	List Docker containers with status, ports, and health
check_port_conflicts	Check if a specific port is in use on the system
tail_system_logs	Retrieve recent system or Docker container logs
get_disk_usage	Get disk usage statistics for filesystems
monitor_cpu_ram	Monitor CPU and RAM usage with configurable sampling

🔧 Features

• 🐳 Docker Integration - List containers, fetch logs, monitor health
• 🔌 Port Monitoring - Detect port conflicts before deployment
• 📊 System Metrics - Real-time CPU, RAM, and disk usage
• 📝 Log Access - System and container log streaming
• 🔒 Read-Only Safety - All operations are non-destructive
• ⚡ Low Latency - Optimized system calls for fast responses
• 🛡️ Strict Validation - Zod schemas ensure safe argument parsing
• 🌐 Cross-Platform - Works on Linux, macOS, and Windows

🏗 Architecture

graph TD
    A[AI Client] -->|MCP Protocol| B[MCP Terminal Monitor Server]
    B -->|Docker API| C[Docker Daemon]
    B -->|System Calls| D[OS Kernel]
    B -->|Network Stats| E[Netstat/Lsof]
    B -->|Process Info| F[SystemInformation]
    
    C --> G[Containers]
    D --> H[CPU/RAM/Disk]
    E --> I[Port Conflicts]
    F --> J[System Metrics]

📖 Usage Examples

List Docker Containers

{
  "name": "list_docker_containers",
  "arguments": {
    "all": true,
    "limit": 10
  }
}

Check Port Conflicts

{
  "name": "check_port_conflicts",
  "arguments": {
    "port": 3000,
    "host": "0.0.0.0"
  }
}

Tail System Logs

{
  "name": "tail_system_logs",
  "arguments": {
    "service": "nginx",
    "lines": 50,
    "follow": false
  }
}

Get Disk Usage

{
  "name": "get_disk_usage",
  "arguments": {
    "path": "/"
  }
}

Monitor CPU & RAM

{
  "name": "monitor_cpu_ram",
  "arguments": {
    "interval": 1000,
    "samples": 3
  }
}

🔌 MCP Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "terminal-monitor": {
      "command": "npx",
      "args": ["mcp-terminal-monitor"]
    }
  }
}

🛠 Development

# Clone repository
git clone https://github.com/yourusername/mcp-terminal-monitor.git
cd mcp-terminal-monitor

# Install dependencies
npm install

# Run in development mode
npm start

# Build for production
npm run build

📦 Requirements

• Node.js >= 18.0.0
• Docker daemon (for Docker-related tools)
• Root/sudo access may be required for some system calls

📄 License

MIT © Your Name

---

Built with @modelcontextprotocol/sdk