# DevOps Dashboard MCP Server

Monitor and manage Linux infrastructure through your AI assistant. Built on the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), this server gives Claude (or any MCP-compatible client) full visibility into your systems — services, logs, resources, containers, and more.

## Tools

| Tool | Description |
|------|-------------|
| `service_status` | Check systemd service status (active, failed, enabled state, PID, memory) |
| `service_logs` | Fetch journalctl logs with time range, priority, and grep filtering |
| `process_list` | List processes sorted by CPU/memory with optional name filtering |
| `disk_usage` | Disk space and inode usage by mount point |
| `memory_info` | RAM and swap usage, with optional /proc/meminfo details |
| `port_scan` | List listening TCP/UDP ports with associated processes |
| `cron_list` | List cron jobs for any/all users plus system cron files |
| `nginx_config` | Read, validate, and inspect nginx configuration and sites |
| `docker_status` | Container, image, volume, network, and resource usage overview |
| `system_health` | Aggregate health check with thresholds and warnings |

## Quick Start

### Install from npm

```bash
npm install -g @devops-dashboard/mcp-server
```

### Or run directly with npx

```bash
npx @devops-dashboard/mcp-server
```

### Configure in Claude Code

Add to your Claude Code MCP settings (`~/.claude/settings.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "devops-dashboard": {
      "command": "npx",
      "args": ["@devops-dashboard/mcp-server"]
    }
  }
}
```

### Configure in Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "devops-dashboard": {
      "command": "npx",
      "args": ["@devops-dashboard/mcp-server"]
    }
  }
}
```

## Development

```bash
git clone https://github.com/turlockmike/devops-dashboard-mcp.git
cd devops-dashboard-mcp
npm install
npm run dev          # Start with tsx (hot reload)
npm run build        # Compile TypeScript
npm test             # Run test suite
```

## Tool Details

### service_status

Check whether a systemd service is running, its enabled/disabled state, PID, and recent status output.

```
Parameters:
  service (string, required) — Service name (e.g. "nginx", "sshd")
  user (boolean, optional) — Query user-level services (--user)
```

### service_logs

Fetch recent journal logs with powerful filtering. Supports time ranges, priority levels, and text search.

```
Parameters:
  service (string, required) — Service name
  lines (number, 1-1000, default 50) — Number of log lines
  since (string, optional) — Time filter ("1h ago", "today", "2024-01-15")
  priority (string, optional) — Minimum level (emerg/alert/crit/err/warning/notice/info/debug)
  grep (string, optional) — Filter by pattern
  user (boolean, optional) — Query user-level service logs
```

### process_list

List running processes with resource usage. Sort by CPU, memory, PID, or elapsed time.

```
Parameters:
  sort (string, default "cpu") — Sort field: cpu, mem, pid, time
  limit (number, 1-200, default 20) — Number of processes to show
  filter (string, optional) — Filter by process name (case-insensitive)
```

### disk_usage

Show disk space and inode usage. Excludes virtual filesystems for clean output.

```
Parameters:
  path (string, optional) — Specific mount point or path
  human (boolean, default true) — Human-readable sizes
```

### memory_info

RAM, swap, and system load. Detailed mode adds buffer/cache breakdown from /proc/meminfo.

```
Parameters:
  detailed (boolean, default false) — Include /proc/meminfo details
```

### port_scan

List all listening network ports with their owning processes. Uses `ss` with `netstat` fallback.

```
Parameters:
  port (number, 1-65535, optional) — Check a specific port
  protocol (string, default "all") — Filter: tcp, udp, all
```

### cron_list

Enumerate cron jobs across users and system directories.

```
Parameters:
  user (string, optional) — Specific user to query
  all (boolean, default false) — List jobs for ALL users
  include_system (boolean, default true) — Include /etc/crontab and /etc/cron.d/
```

### nginx_config

Read and validate nginx configuration.

```
Parameters:
  action (string, required) — show, test, list_sites, or full_config
  site (string, optional) — Specific site config to read (with "show" action)
```

### docker_status

Docker environment overview. Gracefully handles missing Docker or stopped daemon.

```
Parameters:
  action (string, default "overview") — overview, containers, images, stats, networks, volumes
  filter (string, optional) — Filter by container/image name
```

### system_health

Aggregate health check that inspects memory, disk, load, failed services, and network listeners. Returns HEALTHY or ISSUES DETECTED with specific warnings.

```
Parameters:
  verbose (boolean, default false) — Include full details per subsystem
```

## Requirements

- **Node.js** >= 18
- **Linux** (uses systemd, journalctl, ss, df, free, ps, etc.)
- Optional: Docker, nginx (tools degrade gracefully if not present)

## Architecture

```
src/
├── index.ts          # MCP server entry point, tool registration
├── tools/
│   ├── service.ts    # systemd service status + logs
│   ├── system.ts     # processes, disk, memory, ports, health
│   ├── cron.ts       # cron job listing
│   ├── nginx.ts      # nginx config management
│   └── docker.ts     # Docker container/image tools
└── utils/
    └── exec.ts       # Safe command execution (execFile, no shell)
```

All system commands run through `safeExec()` which uses `execFile` (not `exec`) to prevent shell injection. Commands have configurable timeouts and output size limits.

## License

MIT