🔧 MCP Terminal Monitor

demo

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

Built with @modelcontextprotocol/sdk

MCP Terminal Monitor