Docker MCP Server

A Model Context Protocol (MCP) server that enables Claude and other AI assistants to manage Docker containers, images, networks, and volumes through natural language commands.

Status: Phase 4 - Beta

Phase 4 complete with network and volume management capabilities.

Available Tools

System Tools (Phase 1)

Tool	Description	Status
ping	Test connection to Docker daemon	✅ Available
version	Get Docker version information	✅ Available

Container Management (Phase 2)

Tool	Description	Status
list_containers	List containers with filters (all, limit, status)	✅ Available
start_container	Start a stopped container	✅ Available
stop_container	Stop a running container with timeout	✅ Available
restart_container	Restart a container with timeout	✅ Available
remove_container	Remove a container (force, volumes)	✅ Available
fetch_container_logs	Fetch container logs with tail/timestamps	✅ Available
run_container	Create and start a new container	✅ Available
inspect_container	Get detailed container information	✅ Available

Image Management (Phase 3)

Tool	Description	Status
list_images	List images with filters	✅ Available
pull_image	Pull image from registry with authentication	✅ Available
push_image	Push image to registry with authentication	✅ Available
remove_image	Remove images (force, no-prune options)	✅ Available
build_image	Build image from Dockerfile with context	✅ Available
search_images	Search Docker Hub for images	✅ Available

Network Management (Phase 4)

Tool	Description	Status
list_networks	List all Docker networks with filters	✅ Available
inspect_network	Get detailed network information	✅ Available
create_network	Create a new Docker network with driver support	✅ Available
remove_network	Remove a Docker network	✅ Available
connect_network	Connect a container to a network	✅ Available
disconnect_network	Disconnect a container from a network	✅ Available

Volume Management (Phase 4)

Tool	Description	Status
list_volumes	List all Docker volumes with filters	✅ Available
inspect_volume	Get detailed volume information	✅ Available
create_volume	Create a new Docker volume	✅ Available
remove_volume	Remove a Docker volume (⚠️ destructive)	✅ Available
prune_volumes	Remove all unused volumes (⚠️ destructive)	✅ Available

Roadmap

• Phase 1 ✅ Complete: Basic infrastructure, ping, version tools
• Phase 2 ✅ Complete: Container management (list, start, stop, logs, run, inspect)
• Phase 3 ✅ Complete: Image management (list, pull, push, remove, build, search)
• Phase 4 ✅ Complete: Network and volume management (list, create, remove, connect/disconnect)
• Phase 5 (Next): Polish, advanced features, production release

Requirements

• Go 1.21 or higher
• Docker Engine running locally or accessible via DOCKER_HOST
• Claude Desktop or another MCP-compatible client

Installation

Build from Source

# Clone or navigate to the repository
cd docker-mcp-server

# Build the binary
go build -o docker-mcp-server

# Make it executable (Unix-like systems)
chmod +x docker-mcp-server

Cross-Platform Builds

# Linux (amd64)
GOOS=linux GOARCH=amd64 go build -o docker-mcp-server-linux-amd64

# macOS (arm64, Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o docker-mcp-server-darwin-arm64

# macOS (amd64, Intel)
GOOS=darwin GOARCH=amd64 go build -o docker-mcp-server-darwin-amd64

# Windows (amd64)
GOOS=windows GOARCH=amd64 go build -o docker-mcp-server-windows-amd64.exe

Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "docker": {
      "command": "/absolute/path/to/docker-mcp-server",
      "args": [],
      "env": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      }
    }
  }
}

Environment Variables

Variable	Description	Default
DOCKER_HOST	Docker daemon socket or TCP address	unix:///var/run/docker.sock
DOCKER_TLS_VERIFY	Enable TLS verification	Not set
DOCKER_CERT_PATH	Path to TLS certificates	Not set

Remote Docker Host

To connect to a remote Docker host:

{
  "mcpServers": {
    "docker-remote": {
      "command": "/path/to/docker-mcp-server",
      "env": {
        "DOCKER_HOST": "tcp://192.168.1.100:2375"
      }
    }
  }
}

SSH Connection

{
  "mcpServers": {
    "docker-ssh": {
      "command": "/path/to/docker-mcp-server",
      "env": {
        "DOCKER_HOST": "ssh://user@remote-host"
      }
    }
  }
}

Testing

Using MCP Inspector

# Install MCP Inspector (Node.js required)
npx @modelcontextprotocol/inspector ./docker-mcp-server

# The inspector will open in your browser
# Test available tools:
# 1. tools/list - Should show 27 tools (2 system + 8 container + 6 image + 6 network + 5 volume)
# 2. tools/call ping - Should return "Docker daemon is reachable"
# 3. tools/call version - Should return Docker version information
# 4. tools/call list_containers - Should list running containers
# 5. tools/call list_images - Should list Docker images
# 6. tools/call list_networks - Should list Docker networks
# 7. tools/call list_volumes - Should list Docker volumes

Manual Testing

# Verify Docker is running
docker ps

# Build the server
go build -o docker-mcp-server

# Test the binary (it will wait for MCP protocol input on stdin)
# Press Ctrl+C to exit
./docker-mcp-server

Using with Claude Desktop

1. Build and configure as described above
2. Restart Claude Desktop
3. Start a conversation and try:

System commands:

• "What Docker tools do you have?"
• "Ping the Docker daemon"
• "What version of Docker am I running?"

Container management:

• "List all running containers"
• "Show me all containers including stopped ones"
• "Start the container named my-app"
• "Stop container abc123 with 5 second timeout"
• "Get logs from container my-app, last 50 lines"
• "Run a new nginx container on port 8080"
• "Inspect container my-app and show its configuration"
• "Remove stopped container abc123"

Image management:

• "List all Docker images"
• "Search for nginx images on Docker Hub"
• "Pull the nginx:alpine image"
• "Remove the image nginx:latest"
• "Build an image from Dockerfile in current directory"

Network management:

• "List all Docker networks"
• "Create a new bridge network named my-network"
• "Connect container my-app to network my-network"
• "Inspect network bridge"
• "Disconnect container from network"

Volume management:

• "List all Docker volumes"
• "Create a new volume named my-data"
• "Inspect volume my-data"
• "Remove unused volumes"

Usage Examples

Container Management

List all running containers:

Claude: "List all running Docker containers"

List all containers including stopped:

Claude: "Show me all containers including stopped ones"

Start a container:

Claude: "Start the container named my-nginx"

Stop a container with custom timeout:

Claude: "Stop container abc123 with 30 second timeout"

Get container logs:

Claude: "Get the last 100 lines of logs from container my-app"
Claude: "Show all logs from container nginx-prod with timestamps"

Run a new container:

Claude: "Run a new nginx container named web-server on port 8080"
Claude: "Create and start a redis container with port 6379 exposed"

Inspect container details:

Claude: "Inspect container my-app and show its configuration"

Remove a stopped container:

Claude: "Remove the stopped container abc123"
Claude: "Force remove container xyz789 and its volumes"

Restart a container:

Claude: "Restart the container named api-server"

Image Management

List all images:

Claude: "List all Docker images on my system"

Search Docker Hub:

Claude: "Search for official nginx images on Docker Hub"

Pull an image:

Claude: "Pull the nginx:alpine image from Docker Hub"
Claude: "Pull redis:latest"

Push an image:

Claude: "Push myapp:latest to Docker Hub"

Remove an image:

Claude: "Remove the image nginx:old-version"
Claude: "Force remove the image abc123"

Build an image:

Claude: "Build an image from Dockerfile in current directory with tag myapp:v1.0"
Claude: "Build image with context ./app and tags myapp:latest, myapp:1.0"

Network Management

List all networks:

Claude: "List all Docker networks"
Claude: "Show me Docker networks filtered by driver=bridge"

Create a network:

Claude: "Create a new bridge network named my-app-network"
Claude: "Create an internal network named backend-net with subnet 172.20.0.0/16"

Inspect a network:

Claude: "Inspect the bridge network and show its configuration"
Claude: "Get details about the my-app-network network"

Connect container to network:

Claude: "Connect container my-app to network my-app-network"
Claude: "Connect nginx container to backend-net with alias web-server"

Disconnect container from network:

Claude: "Disconnect container my-app from network my-app-network"

Remove a network:

Claude: "Remove the network my-app-network"

Volume Management

List all volumes:

Claude: "List all Docker volumes"
Claude: "Show me volumes that are dangling"

Create a volume:

Claude: "Create a new volume named my-data"
Claude: "Create a volume with custom driver options"

Inspect a volume:

Claude: "Inspect volume my-data and show its configuration"

Remove a volume:

Claude: "Remove the volume old-data"
Claude: "Force remove volume my-data even if it's in use"

Prune unused volumes:

Claude: "Remove all unused Docker volumes to free up space"

Development

Project Structure

docker-mcp-server/
├── main.go                    # Entry point
├── go.mod                     # Go module definition
├── internal/
│   ├── docker/
│   │   ├── client.go          # Docker client wrapper
│   │   ├── system.go          # System operations (ping, version)
│   │   ├── container.go       # Container operations (Phase 2)
│   │   ├── image.go           # Image operations (Phase 3)
│   │   ├── network.go         # Network operations (Phase 4)
│   │   └── volume.go          # Volume operations (Phase 4)
│   ├── tools/
│   │   ├── registry.go        # Tool registration
│   │   ├── system.go          # System tool handlers
│   │   ├── container.go       # Container tool handlers (Phase 2)
│   │   ├── image.go           # Image tool handlers (Phase 3)
│   │   ├── network.go         # Network tool handlers (Phase 4)
│   │   └── volume.go          # Volume tool handlers (Phase 4)
│   └── types/
│       ├── inputs.go          # Input struct definitions
│       └── errors.go          # Error types
└── examples/
    └── claude_desktop_config.json

Adding New Tools

Upcoming phases:

• Phase 5 (Next): Advanced features (exec, stats, additional image/container tools)

For implementation details, see:

• PHASE1_IMPLEMENTATION_PLAN.md
• PHASE2_IMPLEMENTATION_PLAN.md
• PHASE3_IMPLEMENTATION_PLAN.md
• PHASE4_IMPLEMENTATION_PLAN.md

Security Considerations

• Never expose the Docker socket without proper authentication
• Be cautious when using remote Docker connections
• Review containers created by the AI before production use
• Avoid storing sensitive data in container configurations

Troubleshooting

Server won't start

# Check Docker is running
docker ps

# Check Docker socket permissions
ls -la /var/run/docker.sock

# View server logs (they go to stderr)
./docker-mcp-server 2>&1 | tee server.log

Claude Desktop doesn't see the server

1. Verify the config file path is correct
2. Ensure the binary path in config is absolute
3. Check permissions on the binary
4. Restart Claude Desktop completely
5. Check Claude Desktop logs

Connection errors

• Verify DOCKER_HOST is set correctly
• Check firewall settings for remote connections
• Ensure Docker daemon is accessible

Contributing

This project is in early development. Contributions are welcome once we reach Phase 2.

References

• MCP Specification
• MCP Go SDK
• Docker Engine API
• Python Docker MCP Server (inspiration)

License

MIT License (to be added)

Version

Current: 0.4.0-beta (Phase 4 - Network & Volume Management Complete)