# mcp-remote-docker

An MCP (Model Context Protocol) server that bridges your local development environment with a remote Docker host over SSH. Manage containers, stream logs, transfer files, and orchestrate deployments — all from your AI-powered IDE.

## Features

- **Docker Management** — List, start, stop, restart, remove, run, and inspect containers remotely
- **Docker Compose** — Run any `docker compose` subcommand on the remote server
- **Image Builds** — Build Docker images on the remote server
- **Log Fetching** — Tail container or compose logs with filtering by time range
- **File Transfer** — Sync files to the remote server via `rsync` (falls back to `scp`)
- **Remote Execution** — Run arbitrary shell commands on the remote server
- **Deploy Orchestration** — One-command pipeline: sync files → build → restart → fetch logs

## Prerequisites

- **Node.js** >= 18
- **SSH access** to your remote Docker host (key-based auth recommended)
- **Docker** installed on the remote server
- **rsync** on both local and remote machines (optional, falls back to `scp`)

## Installation

```bash
git clone https://github.com/luisf371/Docker-mcp-server.git
cd Docker-mcp-server
npm install
```

## Configuration

All configuration is via environment variables:

| Variable | Default | Description |
|---|---|---|
| `SSH_HOST` | `user@your-remote-server` | SSH connection string |
| `SSH_PORT` | `22` | SSH port |
| `SSH_KEY_PATH` | (none) | Path to SSH private key |
| `REMOTE_PATH` | `/home/user/app` | Default remote working directory |
| `SSH_TIMEOUT` | `30` | SSH connection timeout (seconds) |
| `DEFAULT_LOG_LINES` | `100` | Default number of log lines to tail |

## MCP Configuration

### VS Code (Copilot)

Add to your `.vscode/mcp.json` or VS Code `settings.json`:

```json
{
  "mcpServers": {
    "remote-docker": {
      "command": "node",
      "args": ["/path/to/Docker-mcp-server/dist/index.js"],
      "env": {
        "SSH_HOST": "deploy@192.168.1.100",
        "REMOTE_PATH": "/home/deploy/myapp"
      }
    }
  }
}
```

### Claude Code

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "remote-docker": {
      "command": "node",
      "args": ["/path/to/Docker-mcp-server/dist/index.js"],
      "env": {
        "SSH_HOST": "deploy@192.168.1.100",
        "REMOTE_PATH": "/home/deploy/myapp"
      }
    }
  }
}
```

### Using npx (without cloning)

```json
{
  "mcpServers": {
    "remote-docker": {
      "command": "npx",
      "args": ["-y", "mcp-remote-docker"],
      "env": {
        "SSH_HOST": "deploy@192.168.1.100",
        "REMOTE_PATH": "/home/deploy/myapp"
      }
    }
  }
}
```

## Available Tools

### Docker Management

| Tool | Description |
|---|---|
| `docker_list_containers` | List containers (optionally include stopped) |
| `docker_start` | Start a container |
| `docker_stop` | Stop a container |
| `docker_restart` | Restart a container |
| `docker_remove` | Remove a container |
| `docker_run` | Run a new container with ports, volumes, env vars |
| `docker_build` | Build a Docker image |
| `docker_compose` | Run any docker compose subcommand |
| `docker_inspect` | Inspect a container's details |

### Logging

| Tool | Description |
|---|---|
| `docker_logs` | Fetch logs from a specific container |
| `docker_compose_logs` | Fetch logs from docker compose services |

### File Transfer

| Tool | Description |
|---|---|
| `file_sync` | Sync local files to remote server (rsync/scp) |

### Remote Execution

| Tool | Description |
|---|---|
| `remote_exec` | Execute any command on the remote server |

### Deploy

| Tool | Description |
|---|---|
| `deploy` | Full pipeline: sync → build → restart → logs |

## Example Usage

Once configured, you can use natural language in your AI assistant:

- *"List all running containers on the remote server"*
- *"Show me the last 200 lines of logs from the web container"*
- *"Deploy my local ./src folder to the remote server and restart"*
- *"Run docker compose up -d on the remote server"*
- *"Sync my project files excluding node_modules and .git"*

## Security Notes

- SSH keys should have minimal required permissions
- Consider using a dedicated deploy user with limited sudo access
- The `remote_exec` tool can run arbitrary commands — restrict access as needed
- Never commit SSH keys or credentials to the repository

## License

MIT