# MCP SSH SRE

An MCP server providing read-only server monitoring tools to AI assistants. Runs predefined diagnostic commands over SSH and passes only the results to the LLM - your server credentials and shell are never exposed.

## Quick Start (Docker)

Pre-built images available on [GitHub Container Registry](https://github.com/jeprecated/mcp-ssh-sre/pkgs/container/mcp-ssh-sre).

```bash
docker run -d \
  -p 3000:3000 \
  -e SSH_HOST=server.local \
  -e SSH_USERNAME=mcp-readonly \
  -e SSH_KEY_PATH=/keys/id_ed25519 \
  -v ~/.ssh/id_ed25519_mcp:/keys/id_ed25519:ro \
  ghcr.io/jeprecated/mcp-ssh-sre:latest
```

Then add to your MCP client:

```json
{
  "mcpServers": {
    "ssh-sre": {
      "url": "http://your-server:3000/mcp"
    }
  }
}
```

See [DEPLOYMENT.md](DEPLOYMENT.md) for Docker Compose, local installation, authentication setup, and security configuration.

## Why Use This?

Managing a Linux server involves SSH-ing in, running commands, correlating logs, and interpreting metrics. This MCP server lets AI assistants do that work using natural language.

**Ask questions like:**

- "Why is my Plex container crashing?"
- "Is my array healthy and are there any drives showing signs of failure?"
- "Which containers are consuming the most resources?"
- "Help me debug network connectivity between my nginx and database containers"

Instead of manually running `docker logs`, `smartctl`, `docker inspect`, and correlating outputs, your AI assistant does it in seconds.

## Supported Platforms

| Platform | Status | Tools |
|----------|--------|-------|
| **Unraid** | Full support | 12 modules (10 core + 2 Unraid-specific) |
| **Generic Linux** | Full support | 10 core modules |
| **TrueNAS** | Untested (PRs welcome) | Core tools should work |
| **Proxmox** | Untested (PRs welcome) | Core tools should work |

The server auto-detects your platform at startup and loads appropriate tools.

## Features

- **12 tool modules with 79+ actions** for comprehensive server management
- **Dual transport** - Stdio (local) or HTTP/SSE (network-accessible)
- **Read-only by design** - Zero risk of accidental modifications
- **Docker management** - Logs, stats, environment, ports, network topology
- **Storage & array** - Parity checks, SMART data, temperatures, mover logs (Unraid)
- **Health diagnostics** - Aggregated status with automatic issue detection
- **System monitoring** - Processes, disk I/O, network connections
- **Log analysis** - Search across containers and system logs
- **VM management** - List, inspect, VNC details, libvirt logs
- **Security auditing** - Port scanning, login monitoring, permission audits

## Why SSH Instead of Platform APIs?

| Feature | APIs | SSH |
|---------|------|-----|
| Docker container logs | ❌ | ✅ |
| SMART disk health data | ❌ | ✅ |
| Real-time CPU/load averages | ❌ | ✅ |
| Network bandwidth monitoring | ❌ | ✅ |
| Process monitoring (ps/top) | ❌ | ✅ |
| Log file analysis | ❌ | ✅ |

SSH provides unrestricted access to system tools without API rate limiting.

## Architecture

```
src/
├── platforms/
│   ├── linux/        # Generic Linux (baseline)
│   └── unraid/       # Unraid-specific tools
├── tools/core/       # 10 core tool modules
├── index.ts          # Stdio transport
└── http-server.ts    # HTTP transport
```

### Adding New Platforms

1. Create `src/platforms/<platform>/index.ts` implementing `Platform`
2. Add detection logic
3. Create platform-specific tool modules
4. Register in `src/platforms/index.ts`

## Development

```bash
npm run dev      # Development with auto-reload
npm test         # Run tests
npm run build    # Build for production
```

## License

ISC

## Support

For issues and questions, open an issue on the [GitHub repository](https://github.com/jeprecated/mcp-ssh-sre).