mcp-remote-docker

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

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:

{
  "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:

{
  "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)

{
  "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