# MCP System Monitor

A production-grade Model Context Protocol (MCP) server that provides Claude with comprehensive system monitoring and diagnostics capabilities.

## What It Does

This MCP server gives Claude direct access to system metrics and diagnostics, enabling it to:

- Monitor CPU, memory, and disk usage in real-time
- Analyze running processes and resource consumption
- Inspect network connections and listening ports
- Monitor Docker containers and images
- Access system logs via journalctl (Linux)

Perfect for system diagnostics, performance troubleshooting, DevOps automation, and infrastructure monitoring.

## Features

### Available Tools

1. **get_system_resources** - Real-time system resource monitoring
   - CPU usage, cores, and load
   - Memory usage and swap statistics
   - Disk usage and filesystem info
   - System uptime and OS details

2. **list_processes** - Process monitoring and analysis
   - Top processes by CPU or memory usage
   - Process state and resource consumption
   - Command line and user information
   - Sortable and filterable results

3. **get_network_connections** - Network connection analysis
   - Active network connections
   - Listening ports and services
   - Connection states (ESTABLISHED, LISTEN, etc.)
   - Process-to-port mapping

4. **get_docker_status** - Docker container monitoring
   - Running and stopped containers
   - Container status and health
   - Image inventory
   - Port mappings and resource usage

5. **get_system_logs** - System log analysis (Linux only)
   - Recent journalctl entries
   - Filterable by priority level
   - Filterable by systemd unit
   - Structured log output

## Installation

```bash
cd mcp-system-monitor
npm install
npm run build
```

## Configuration

### Claude Code Configuration

Add to your Claude Code MCP settings (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "system-monitor": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-system-monitor/dist/index.js"]
    }
  }
}
```

### Permissions

Some features require elevated permissions:

- **Docker status**: User must be in the `docker` group
- **System logs**: May require sudo access to journalctl (depending on system configuration)
- **Process details**: Full process info may require elevated privileges

## Example Usage with Claude Code

Once configured, you can ask Claude:

> "What's my current CPU and memory usage?"

> "Show me the top 10 processes by CPU usage"

> "List all listening ports and which processes are using them"

> "What Docker containers are running right now?"

> "Show me the last 100 error-level system logs"

> "Which process is using port 8080?"

> "Is my disk usage getting high?"

## Platform Support

- **CPU/Memory/Disk/Processes**: All platforms (Linux, macOS, Windows)
- **Network connections**: All platforms
- **Docker status**: Requires Docker installation
- **System logs**: Linux only (requires systemd/journalctl)

Gracefully degrades on platforms where features aren't available.

## Development

```bash
# Watch mode for development
npm run dev

# Build for production
npm run build

# Start the server
npm start
```

## Security Considerations

This server provides read-only access to system information. It does not:
- Modify system configuration
- Kill or start processes
- Change permissions
- Execute arbitrary commands

However, it does expose system information including:
- Running processes and their arguments
- Network connections
- System logs

Only use in trusted environments and be mindful of what information you share.

## Error Handling

The server includes comprehensive error handling for:
- Missing system utilities (docker, journalctl)
- Permission denied errors
- Platform-specific features
- Malformed data
- Schema validation errors

Features that aren't available will return clear messages instead of errors.

## Tech Stack

- TypeScript for type safety
- @modelcontextprotocol/sdk for MCP protocol
- systeminformation for cross-platform system metrics
- Zod for runtime schema validation
- Native child_process for Docker and journalctl integration

## Use Cases

- **DevOps**: Automated system health checks
- **Troubleshooting**: Quick diagnostics without leaving Claude
- **Monitoring**: Resource usage tracking and alerting
- **Documentation**: Generate system reports and inventories
- **Development**: Debug resource leaks and performance issues

## License

MIT