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