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)

For Developers

✨ 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)

From Source

Prerequisites

• Node.js 18 or higher

• Docker installed and running

• npm or yarn package manager

Setup

1. Clone the repository:

2. Install dependencies:

3. Build the project:

Usage

Standalone Mode

Run the server directly:

Remote Docker Configuration

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

Connect to Remote Docker via TCP

Connect to Remote Docker via HTTPS with TLS

Connect via SSH Tunnel

First, set up an SSH tunnel:

Then connect to the tunneled Docker:

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):

For Remote Docker over TCP:

For Remote Docker with TLS:

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

Alternative using npx (after publishing to npm):

Testing Your Connection

Connection Test Utility

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

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:

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:

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)

create_container

Create a new Docker container

run_container

Create and start a container (recommended)

start_container

Start a stopped container

stop_container

Stop a running container

remove_container

Remove a container

inspect_container

Get detailed container information

container_logs

Get container logs

exec_container 🆕

Execute a command in a running container

container_stats 🆕

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

restart_container 🆕

Restart a Docker container

pause_container 🆕

Pause all processes within a container

unpause_container 🆕

Unpause all processes within a container

rename_container 🆕

Rename a Docker container

prune_containers 🆕

Remove all stopped containers

Image Operations (7 tools)

list_images

List Docker images

pull_image

Pull an image from registry

build_image 🆕

Build a Docker image from a Dockerfile

tag_image 🆕

Tag an image with a new name/tag

push_image 🆕

Push an image to a Docker registry

remove_image 🆕

Remove a Docker image

prune_images 🆕

Remove unused images

Network Operations (7 tools)

list_networks

List Docker networks

create_network 🆕

Create a Docker network

inspect_network 🆕

Get detailed information about a network

connect_network 🆕

Connect a container to a network

disconnect_network 🆕

Disconnect a container from a network

remove_network 🆕

Remove a Docker network

prune_networks 🆕

Remove all unused networks

Volume Operations (5 tools)

list_volumes

List Docker volumes

create_volume 🆕

Create a Docker volume

inspect_volume 🆕

Get detailed information about a volume

remove_volume 🆕

Remove a Docker volume

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

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:

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 (eternusprocer@gmail.com)