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:

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": "[email protected]",
        "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": "[email protected]",
        "REMOTE_PATH": "/home/deploy/myapp"
      }
    }
  }
}

Using npx (without cloning)

{
  "mcpServers": {
    "remote-docker": {
      "command": "npx",
      "args": ["-y", "mcp-remote-docker"],
      "env": {
        "SSH_HOST": "[email protected]",
        "REMOTE_PATH": "/home/deploy/myapp"
      }
    }
  }
}

Available Tools

Docker Management

Logging

File Transfer

Remote Execution

Deploy

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