# Docker MCP

> Personal note: Keep in mind that all AIs are essentially retarded geniuses. Refactor instructions as needed if your child acts up.
 
Remote Docker management over SSH — exposed as a local MCP server for GitHub Copilot sessions.

No server-side component required. The MCP runs locally and SSHes into the remote host to execute Docker commands.

## Tools

| Tool | Description |
|---|---|
| `docker_ps` | List containers |
| `docker_logs` | Fetch logs (tail, since, grep) |
| `docker_exec` | Run command inside container |
| `docker_run` | Start new container |
| `docker_start` / `docker_stop` / `docker_restart` | Lifecycle control |
| `docker_rm` | Remove container(s) |
| `docker_inspect` | Detailed container/image info |
| `docker_stats` | Resource usage snapshot |
| `docker_top` | Processes inside container |
| `docker_images` | List images |
| `docker_pull` / `docker_rmi` / `docker_build` | Image management |
| `docker_compose_ps/up/down/logs/restart/pull` | Compose operations |
| `docker_system_df` | Disk usage |
| `docker_info` / `docker_version` | System info |
| `docker_network_ls` / `docker_volume_ls` | Network & volume listing |

## Setup

### 1. Clone the repository

```bash
git clone git@github.com:Isak-Landin/mcp-docker-engine.git ~/mcp-docker-engine
cd ~/mcp-docker-engine
```

### 2. Install dependencies

```bash
sudo apt install python3.12-venv
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

### 3. Configure SSH target

```bash
cp config.example.json config.json
# Edit config.json with your server details
```

`config.json` fields:

```json
{
  "host": "your-server.example.com",
  "user": "ubuntu",
  "key_path": "~/.ssh/id_rsa",
  "port": 22
}
```

### 4. Verify SSH access

Using the values from your `config.json`:

```bash
ssh -i <key_path> <user>@<host> docker ps
```

### 5. Register with GitHub Copilot

#### Copilot CLI — `mcp-config.json`

Add the `docker-mcp` entry to the `mcpServers` object in your Copilot home's `mcp-config.json`:

```json
"docker-mcp": {
  "command": "/home/<your-username>/mcp-docker-engine/.venv/bin/python3",
  "args": ["/home/<your-username>/mcp-docker-engine/server.py"]
}
```

#### VS Code — `.vscode/mcp.json`

Add the `docker-mcp` entry to the `servers` object:

```json
"docker-mcp": {
  "type": "stdio",
  "command": "/home/<your-username>/mcp-docker-engine/.venv/bin/python3",
  "args": ["/home/<your-username>/mcp-docker-engine/server.py"]
}
```

#### Copilot instructions — `copilot-instructions.md`

Add the contents of `copilot-instructions.md` to your Copilot home's `copilot-instructions.md` or `instructions.md`.

## Notes

- The SSH connection uses `StrictHostKeyChecking=accept-new` - safe for known hosts, will warn on key changes.
- `docker_build` and `docker_pull` use a 5-10 min timeout; adjust `timeout` in `server.py` if needed.
- For Compose tools, `project_dir` is the **remote** path containing `docker-compose.yml`.
- `docker_logs` and `docker_exec` redirect stderr to stdout so output is always captured.