# Docker MCP Server
[](https://www.npmjs.com/package/@swartdraak/docker-mcp-server)
[](https://www.npmjs.com/package/@swartdraak/docker-mcp-server)
[](https://github.com/Swartdraak/Docker-MCP/actions/workflows/ci.yml)
[](https://github.com/Swartdraak/Docker-MCP/actions/workflows/codeql.yml)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://www.docker.com/)
[](https://semver.org/)
> 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](#about)
- [Quick Start](#quick-start)
- [Features](#-features)
- [Installation](#installation)
- [Usage](#usage)
- [Available Tools](#available-tools-37-total)
- [Testing Your Connection](#testing-your-connection)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [Documentation](#documentation)
- [License](#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)
```bash
# Install globally
npm install -g @swartdraak/docker-mcp-server
# Or use with npx (no installation needed)
npx @swartdraak/docker-mcp-server
```
### For Developers
```bash
# 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)
```bash
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:
```bash
git clone https://github.com/Swartdraak/Docker-MCP.git
cd Docker-MCP
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
## Usage
### Standalone Mode
Run the server directly:
```bash
npm start
```
### Remote Docker Configuration
The MCP server supports connecting to remote Docker hosts using environment variables:
#### Connect to Remote Docker via TCP
```bash
DOCKER_HOST=tcp://192.168.1.100:2375 npm start
```
#### Connect to Remote Docker via HTTPS with TLS
```bash
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:
```bash
ssh -NL localhost:2375:/var/run/docker.sock user@remote-host
```
Then connect to the tunneled Docker:
```bash
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):
```json
{
"mcpServers": {
"docker": {
"command": "node",
"args": ["/path/to/Docker-MCP/dist/index.js"]
}
}
}
```
**For Remote Docker over TCP**:
```json
{
"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**:
```json
{
"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):
```json
{
"mcpServers": {
"docker": {
"command": "node",
"args": ["/path/to/Docker-MCP/dist/index.js"]
}
}
}
```
**Alternative using npx** (after publishing to npm):
```json
{
"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:
```bash
# 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:
```bash
# 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](CONFIGURATION.md)** - MCP server configuration examples
- **[REMOTE_SETUP.md](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)
```json
{
"all": true
}
```
#### `create_container`
Create a new Docker container
```json
{
"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)
```json
{
"image": "python:3.9",
"name": "my-python-app",
"command": ["python", "app.py"],
"env": ["DEBUG=true", "PORT=5000"]
}
```
#### `start_container`
Start a stopped container
```json
{
"containerId": "container_id_or_name"
}
```
#### `stop_container`
Stop a running container
```json
{
"containerId": "container_id_or_name",
"timeout": 10
}
```
#### `remove_container`
Remove a container
```json
{
"containerId": "container_id_or_name",
"force": false,
"volumes": false
}
```
#### `inspect_container`
Get detailed container information
```json
{
"containerId": "container_id_or_name"
}
```
#### `container_logs`
Get container logs
```json
{
"containerId": "container_id_or_name",
"tail": 100,
"follow": false
}
```
#### `exec_container` 🆕
Execute a command in a running container
```json
{
"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)
```json
{
"containerId": "container_id_or_name",
"stream": false
}
```
#### `restart_container` 🆕
Restart a Docker container
```json
{
"containerId": "container_id_or_name",
"timeout": 10
}
```
#### `pause_container` 🆕
Pause all processes within a container
```json
{
"containerId": "container_id_or_name"
}
```
#### `unpause_container` 🆕
Unpause all processes within a container
```json
{
"containerId": "container_id_or_name"
}
```
#### `rename_container` 🆕
Rename a Docker container
```json
{
"containerId": "container_id_or_name",
"newName": "new-container-name"
}
```
#### `prune_containers` 🆕
Remove all stopped containers
```json
{}
```
### Image Operations (7 tools)
#### `list_images`
List Docker images
```json
{
"all": false
}
```
#### `pull_image`
Pull an image from registry
```json
{
"image": "nginx:latest"
}
```
#### `build_image` 🆕
Build a Docker image from a Dockerfile
```json
{
"context": "/path/to/build/context",
"dockerfile": "Dockerfile",
"tag": "myimage:latest",
"buildArgs": {
"NODE_VERSION": "18"
}
}
```
#### `tag_image` 🆕
Tag an image with a new name/tag
```json
{
"image": "myimage:latest",
"repo": "myrepo/myimage",
"tag": "v1.0.0"
}
```
#### `push_image` 🆕
Push an image to a Docker registry
```json
{
"image": "myrepo/myimage:v1.0.0"
}
```
#### `remove_image` 🆕
Remove a Docker image
```json
{
"image": "image_id_or_name",
"force": false
}
```
#### `prune_images` 🆕
Remove unused images
```json
{
"all": false
}
```
### Network Operations (7 tools)
#### `list_networks`
List Docker networks
```json
{}
```
#### `create_network` 🆕
Create a Docker network
```json
{
"name": "my-network",
"driver": "bridge",
"internal": false
}
```
#### `inspect_network` 🆕
Get detailed information about a network
```json
{
"networkId": "network_id_or_name"
}
```
#### `connect_network` 🆕
Connect a container to a network
```json
{
"networkId": "network_id_or_name",
"containerId": "container_id_or_name"
}
```
#### `disconnect_network` 🆕
Disconnect a container from a network
```json
{
"networkId": "network_id_or_name",
"containerId": "container_id_or_name",
"force": false
}
```
#### `remove_network` 🆕
Remove a Docker network
```json
{
"networkId": "network_id_or_name"
}
```
#### `prune_networks` 🆕
Remove all unused networks
```json
{}
```
### Volume Operations (5 tools)
#### `list_volumes`
List Docker volumes
```json
{}
```
#### `create_volume` 🆕
Create a Docker volume
```json
{
"name": "my-volume",
"driver": "local",
"labels": {
"environment": "production"
}
}
```
#### `inspect_volume` 🆕
Get detailed information about a volume
```json
{
"volumeName": "volume_name"
}
```
#### `remove_volume` 🆕
Remove a Docker volume
```json
{
"volumeName": "volume_name",
"force": false
}
```
#### `prune_volumes` 🆕
Remove all unused volumes
```json
{}
```
### System Operations (3 tools)
#### `system_info` 🆕
Get Docker system information
```json
{}
```
#### `system_version` 🆕
Get Docker version information
```json
{}
```
#### `validate_connection` 🆕
Validate Docker connection and test basic operations. Returns connection status, configuration details, and test results. Useful for troubleshooting connection issues.
```json
{}
```
## 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](https://github.com/Swartdraak/Docker-MCP/blob/main/BRANCHING.md))
- **Versioning**: Semantic Versioning 2.0.0 (see [VERSIONING.md](https://github.com/Swartdraak/Docker-MCP/blob/main/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](https://github.com/Swartdraak/Docker-MCP/blob/main/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:
```bash
# 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](https://github.com/Swartdraak/Docker-MCP/blob/main/VERSIONING.md) for complete release procedures.
For detailed usage examples, see [EXAMPLES.md](EXAMPLES.md).
For configuration help, see [CONFIGURATION.md](CONFIGURATION.md).
## Documentation
### User Documentation
- [README.md](README.md) - Main documentation and quick start
- [CONFIGURATION.md](CONFIGURATION.md) - Configuration options and setup
- [EXAMPLES.md](EXAMPLES.md) - Usage examples for all tools
- [REMOTE_SETUP.md](https://github.com/Swartdraak/Docker-MCP/blob/main/REMOTE_SETUP.md) - Remote Docker connection setup
- [MIGRATION.md](https://github.com/Swartdraak/Docker-MCP/blob/main/MIGRATION.md) - Migration guides for version upgrades
### Developer Documentation
- [CONTRIBUTING.md](https://github.com/Swartdraak/Docker-MCP/blob/main/CONTRIBUTING.md) - Contribution guidelines and workflow
- [BRANCHING.md](https://github.com/Swartdraak/Docker-MCP/blob/main/BRANCHING.md) - Git Flow branching strategy
- [VERSIONING.md](https://github.com/Swartdraak/Docker-MCP/blob/main/VERSIONING.md) - Semantic versioning and release process
- [RELEASE_GUIDE.md](RELEASE_GUIDE.md) - npm package release procedures
- [BRANCH_PROTECTION.md](https://github.com/Swartdraak/Docker-MCP/blob/main/BRANCH_PROTECTION.md) - Branch protection setup guide
- [CHANGELOG.md](CHANGELOG.md) - Version history and changes
- [SECURITY.md](https://github.com/Swartdraak/Docker-MCP/blob/main/SECURITY.md) - Security policies and reporting
## License
MIT License - see LICENSE file for details
## Author
Swartdraak (eternusprocer@gmail.com)
