Docker MCP Server

A comprehensive, production-ready, industry-standard compliant MCP (Model Context Protocol) Server that enables full Docker management capabilities for AI assistants like GitHub Copilot and Claude. Featuring 37 powerful tools covering containers, images, networks, volumes, and system operations.

📋 Table of Contents

• About
• Quick Start
• Features
• Installation
• Usage
• Available Tools
• Testing Your Connection
• Development
• Troubleshooting
• Contributing
• Documentation
• License

About

Docker MCP Server is a Model Context Protocol server that bridges AI assistants with Docker, enabling natural language Docker operations. Built with TypeScript and following industry best practices, it provides a complete Docker management solution for AI-powered development workflows.

Why Docker MCP Server?

• 🤖 AI-Native: Designed specifically for AI assistants (GitHub Copilot, Claude)
• 🔧 Complete Coverage: 37 tools covering all essential Docker operations
• 🌐 Remote Support: Connect to Docker on any host via TCP, HTTPS, or SSH tunnel
• 🔒 Security First: Full TLS/SSL support with certificate authentication
• 📦 Production Ready: Comprehensive error handling, type safety, and testing
• 📚 Well Documented: Extensive documentation with examples for every feature
• 🚀 Easy to Use: Simple installation and configuration

Use Cases

• AI-Assisted DevOps: Let AI assistants manage your Docker infrastructure
• Container Orchestration: Create, manage, and monitor containers through natural language
• Development Automation: Automate Docker workflows with AI assistance
• Remote Management: Securely manage Docker on remote hosts
• Learning & Exploration: Explore Docker capabilities with AI guidance

Quick Start

For npm Users (Recommended)

# Install globally
npm install -g @swartdraak/docker-mcp-server

# Or use with npx (no installation needed)
npx @swartdraak/docker-mcp-server

For Developers

# Clone the repository
git clone https://github.com/Swartdraak/Docker-MCP.git
cd Docker-MCP

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

✨ Features

Core Capabilities

• ✅ 37 Docker Tools: Complete coverage of Docker operations including connection validation
• ✅ Remote Docker Support: Connect to Docker on remote hosts via TCP, HTTP, HTTPS, or SSH tunnel
• ✅ Secure Connections: Full TLS/SSL support for secure remote Docker management
• ✅ Container Management: Create, run, start, stop, restart, pause, unpause, rename, remove, exec, stats, logs
• ✅ Image Operations: List, pull, build, push, tag, remove, prune
• ✅ Network Management: List, create, remove, inspect, connect, disconnect
• ✅ Volume Management: List, create, remove, inspect, prune
• ✅ System Operations: Info, version, connection validation, prune (containers, images, volumes, networks)
• ✅ Proper Array Handling: Correctly handles command, entrypoint, and environment variables
• ✅ VS Code Integration: Works seamlessly with GitHub Copilot
• ✅ Industry Standard: Uses MCP SDK and Docker best practices
• ✅ TypeScript: Full type safety and modern JavaScript features

Recent Enhancements

• 🌐 Remote Docker Host Support: Connect to Docker on any remote host
• 🔒 TLS/HTTPS Support: Secure connections with certificate authentication
• 🔑 Environment-based Configuration: Easy setup via DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH
• 🚇 SSH Tunnel Support: Secure remote access without exposing Docker API

What's New in v2.0

• 🚀 25 New Tools: Added extensive container, image, network, and volume management
• 🔧 Container Exec: Execute commands in running containers
• 📊 Container Stats: Real-time CPU, memory, network, and I/O metrics
• 🏗️ Image Building: Build images from Dockerfile with build args
• 🔄 Advanced Lifecycle: Restart, pause, unpause, rename containers
• 🌐 Full Network CRUD: Create, inspect, connect, disconnect, remove networks
• 💾 Full Volume CRUD: Create, inspect, remove volumes
• 🧹 Resource Cleanup: Prune unused containers, images, volumes, networks
• ⚙️ System Info: Get Docker daemon information and version

Installation

Via npm (Recommended)

npm install -g @swartdraak/docker-mcp-server

From Source

Prerequisites

• Node.js 18 or higher
• Docker installed and running
• npm or yarn package manager

Setup

1. Clone the repository:

git clone https://github.com/Swartdraak/Docker-MCP.git
cd Docker-MCP

2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage

Standalone Mode

Run the server directly:

npm start

Remote Docker Configuration

The MCP server supports connecting to remote Docker hosts using environment variables:

Connect to Remote Docker via TCP

DOCKER_HOST=tcp://192.168.1.100:2375 npm start

Connect to Remote Docker via HTTPS with TLS

DOCKER_HOST=https://192.168.1.100:2376 \
DOCKER_TLS_VERIFY=1 \
DOCKER_CERT_PATH=~/.docker/certs \
npm start

Connect via SSH Tunnel

First, set up an SSH tunnel:

ssh -NL localhost:2375:/var/run/docker.sock user@remote-host

Then connect to the tunneled Docker:

DOCKER_HOST=tcp://localhost:2375 npm start

VS Code Integration

To integrate with VS Code and GitHub Copilot, add the following to your MCP settings file:

For Local Docker (~/.vscode/mcp-settings.json or in your workspace settings):

{
  "mcpServers": {
    "docker": {
      "command": "node",
      "args": ["/path/to/Docker-MCP/dist/index.js"]
    }
  }
}

For Remote Docker over TCP:

{
  "mcpServers": {
    "docker": {
      "command": "node",
      "args": ["/path/to/Docker-MCP/dist/index.js"],
      "env": {
        "DOCKER_HOST": "tcp://192.168.1.100:2375"
      }
    }
  }
}

For Remote Docker with TLS:

{
  "mcpServers": {
    "docker": {
      "command": "node",
      "args": ["/path/to/Docker-MCP/dist/index.js"],
      "env": {
        "DOCKER_HOST": "https://192.168.1.100:2376",
        "DOCKER_TLS_VERIFY": "1",
        "DOCKER_CERT_PATH": "/home/user/.docker/certs"
      }
    }
  }
}

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "docker": {
      "command": "node",
      "args": ["/path/to/Docker-MCP/dist/index.js"]
    }
  }
}

Alternative using npx (after publishing to npm):

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["@swartdraak/docker-mcp-server"]
    }
  }
}

Testing Your Connection

Connection Test Utility

Before using the MCP server, you can test your Docker connection with the included test utility:

# Test local Docker connection
node test-connection.js

# Test remote Docker via TCP
DOCKER_HOST=tcp://192.168.1.100:2375 node test-connection.js

# Test remote Docker via TLS
DOCKER_HOST=https://192.168.1.100:2376 \
DOCKER_TLS_VERIFY=1 \
DOCKER_CERT_PATH=~/.docker/certs \
node test-connection.js

# Test SSH tunnel connection
DOCKER_HOST=tcp://localhost:2375 node test-connection.js

The test utility will:

• ✓ Validate your configuration
• ✓ Check TLS certificates (if applicable)
• ✓ Test connection to Docker daemon
• ✓ Verify Docker operations (list containers, images, networks, volumes)
• ✓ Display system information
• ✓ Provide troubleshooting recommendations

validate_connection Tool

Once the MCP server is running, you can also use the validate_connection tool from your AI assistant:

"Validate my Docker connection"

This tool performs runtime connectivity tests and returns:

• Connection status
• Docker version and API information
• System information
• Test results for common operations

Manual Testing

You can also test your connection directly with Docker CLI:

# Set environment variables
export DOCKER_HOST=tcp://192.168.1.100:2375

# Test commands
docker version
docker info
docker ps

For detailed setup instructions, troubleshooting, and platform-specific guides, see:

• CONFIGURATION.md - MCP server configuration examples
• REMOTE_SETUP.md - Comprehensive remote connection setup guide (includes Windows 11 specific instructions)

Available Tools (37 Total)

Container Operations (15 tools)

list_containers

List all Docker containers (running or all)

{
  "all": true
}

create_container

Create a new Docker container

{
  "image": "nginx:latest",
  "name": "my-nginx",
  "command": ["nginx", "-g", "daemon off;"],
  "env": ["NODE_ENV=production"],
  "exposedPorts": {"80/tcp": {}},
  "hostConfig": {
    "PortBindings": {"80/tcp": [{"HostPort": "8080"}]},
    "Binds": ["/host/path:/container/path"]
  }
}

run_container

Create and start a container (recommended)

{
  "image": "python:3.9",
  "name": "my-python-app",
  "command": ["python", "app.py"],
  "env": ["DEBUG=true", "PORT=5000"]
}

start_container

Start a stopped container

{
  "containerId": "container_id_or_name"
}

stop_container

Stop a running container

{
  "containerId": "container_id_or_name",
  "timeout": 10
}

remove_container

Remove a container

{
  "containerId": "container_id_or_name",
  "force": false,
  "volumes": false
}

inspect_container

Get detailed container information

{
  "containerId": "container_id_or_name"
}

container_logs

Get container logs

{
  "containerId": "container_id_or_name",
  "tail": 100,
  "follow": false
}

exec_container 🆕

Execute a command in a running container

{
  "containerId": "container_id_or_name",
  "command": ["ls", "-la", "/app"],
  "workingDir": "/app",
  "env": ["DEBUG=true"]
}

container_stats 🆕

Get real-time resource usage statistics (CPU, memory, network, I/O)

{
  "containerId": "container_id_or_name",
  "stream": false
}

restart_container 🆕

Restart a Docker container

{
  "containerId": "container_id_or_name",
  "timeout": 10
}

pause_container 🆕

Pause all processes within a container

{
  "containerId": "container_id_or_name"
}

unpause_container 🆕

Unpause all processes within a container

{
  "containerId": "container_id_or_name"
}

rename_container 🆕

Rename a Docker container

{
  "containerId": "container_id_or_name",
  "newName": "new-container-name"
}

prune_containers 🆕

Remove all stopped containers

{}

Image Operations (7 tools)

list_images

List Docker images

{
  "all": false
}

pull_image

Pull an image from registry

{
  "image": "nginx:latest"
}

build_image 🆕

Build a Docker image from a Dockerfile

{
  "context": "/path/to/build/context",
  "dockerfile": "Dockerfile",
  "tag": "myimage:latest",
  "buildArgs": {
    "NODE_VERSION": "18"
  }
}

tag_image 🆕

Tag an image with a new name/tag

{
  "image": "myimage:latest",
  "repo": "myrepo/myimage",
  "tag": "v1.0.0"
}

push_image 🆕

Push an image to a Docker registry

{
  "image": "myrepo/myimage:v1.0.0"
}

remove_image 🆕

Remove a Docker image

{
  "image": "image_id_or_name",
  "force": false
}

prune_images 🆕

Remove unused images

{
  "all": false
}

Network Operations (7 tools)

list_networks

List Docker networks

{}

create_network 🆕

Create a Docker network

{
  "name": "my-network",
  "driver": "bridge",
  "internal": false
}

inspect_network 🆕

Get detailed information about a network

{
  "networkId": "network_id_or_name"
}

connect_network 🆕

Connect a container to a network

{
  "networkId": "network_id_or_name",
  "containerId": "container_id_or_name"
}

disconnect_network 🆕

Disconnect a container from a network

{
  "networkId": "network_id_or_name",
  "containerId": "container_id_or_name",
  "force": false
}

remove_network 🆕

Remove a Docker network

{
  "networkId": "network_id_or_name"
}

prune_networks 🆕

Remove all unused networks

{}

Volume Operations (5 tools)

list_volumes

List Docker volumes

{}

create_volume 🆕

Create a Docker volume

{
  "name": "my-volume",
  "driver": "local",
  "labels": {
    "environment": "production"
  }
}

inspect_volume 🆕

Get detailed information about a volume

{
  "volumeName": "volume_name"
}

remove_volume 🆕

Remove a Docker volume

{
  "volumeName": "volume_name",
  "force": false
}

prune_volumes 🆕

Remove all unused volumes

{}

System Operations (3 tools)

system_info 🆕

Get Docker system information

{}

system_version 🆕

Get Docker version information

{}

validate_connection 🆕

Validate Docker connection and test basic operations. Returns connection status, configuration details, and test results. Useful for troubleshooting connection issues.

{}

Key Features: Array Handling

This MCP server correctly handles arrays for:

• Command: Passed as an array of strings ["python", "app.py", "--port", "8000"]
• Entrypoint: Passed as an array of strings ["/bin/bash", "-c"]
• Environment Variables: Passed as an array of KEY=VALUE strings ["NODE_ENV=production", "PORT=3000"]
• Volume Bindings: Passed as an array of bind strings ["/host/path:/container/path"]

This resolves the common "array issue" where MCP servers incorrectly expect strings instead of arrays, causing errors when integrated with VS Code and GitHub Copilot.

Development

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run watch - Watch mode for development
• npm start - Run the compiled server
• npm run dev - Build and run

Project Structure

Docker-MCP/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript output
├── package.json          # Project dependencies
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Troubleshooting

Docker Connection Issues

If you get "Cannot connect to Docker daemon" errors:

• Ensure Docker is running: docker ps
• Check Docker socket permissions
• On Linux: Add your user to the docker group: sudo usermod -aG docker $USER

Remote Docker Connection Issues

If you can't connect to a remote Docker host:

1. TCP Connection Issues:

   • Ensure the Docker daemon is configured to listen on TCP: Check /etc/docker/daemon.json
   • Verify the port is open: telnet remote-host 2375
   • Check firewall rules on the remote host
   • Ensure DOCKER_HOST environment variable is set correctly

2. TLS/HTTPS Connection Issues:

   • Verify certificates are in the correct directory
   • Check certificate file names: ca.pem, cert.pem, key.pem
   • Ensure certificates are readable: chmod 644 ca.pem cert.pem key.pem
   • Verify DOCKER_TLS_VERIFY=1 and DOCKER_CERT_PATH are set
   • Test with Docker CLI first: docker --tlsverify --host=tcp://remote-host:2376 ps

3. SSH Tunnel Issues:

   • Verify SSH tunnel is running: ps aux | grep ssh
   • Test tunnel: curl http://localhost:2375/version
   • Ensure local port is not already in use: lsof -i :2375
   • Try reconnecting the tunnel if connection is lost

VS Code Integration Issues

If the MCP server doesn't appear in VS Code:

• Verify the path to dist/index.js is absolute
• Check that the server builds successfully: npm run build
• Restart VS Code after updating MCP settings
• Check VS Code Output panel for MCP-related errors
• Verify environment variables in MCP settings are correct

Array-Related Errors

This server is specifically designed to handle arrays correctly. If you encounter array errors:

• Ensure you're passing arrays for command, entrypoint, and env fields
• Verify JSON formatting in tool arguments
• Check that arrays contain string items

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Workflow

This project follows industry-standard practices:

• Branching Strategy: Git Flow (see BRANCHING.md)
• Versioning: Semantic Versioning 2.0.0 (see VERSIONING.md)
• Commit Convention: Conventional Commits
• CI/CD: Automated testing and releases via GitHub Actions

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes with conventional commits
4. Ensure tests pass: npm test
5. Push and create a Pull Request to develop

For detailed guidelines, see CONTRIBUTING.md.

Branch Structure

• main - Production releases (protected)
• develop - Integration branch (protected)
• feature/* - New features
• bugfix/* - Bug fixes
• hotfix/* - Critical production fixes

Release Process

Releases are automated via GitHub Actions when tags are pushed:

# Create release branch
git checkout -b release/2.1.0

# Update version and changelog
npm version minor

# Merge to main and tag
git checkout main
git merge --no-ff release/2.1.0
git tag -a v2.1.0 -m "Version 2.1.0"
git push origin main --tags

See VERSIONING.md for complete release procedures.

For detailed usage examples, see EXAMPLES.md.

For configuration help, see CONFIGURATION.md.

Documentation

User Documentation

• README.md - Main documentation and quick start
• CONFIGURATION.md - Configuration options and setup
• EXAMPLES.md - Usage examples for all tools
• REMOTE_SETUP.md - Remote Docker connection setup
• MIGRATION.md - Migration guides for version upgrades

Developer Documentation

• CONTRIBUTING.md - Contribution guidelines and workflow
• BRANCHING.md - Git Flow branching strategy
• VERSIONING.md - Semantic versioning and release process
• RELEASE_GUIDE.md - npm package release procedures
• BRANCH_PROTECTION.md - Branch protection setup guide
• CHANGELOG.md - Version history and changes
• SECURITY.md - Security policies and reporting

License

MIT License - see LICENSE file for details

Author

Swartdraak ([email protected])