Docker MCP
its a basic docker mcp server
Installation
npx docker-mcpAsk AI about Docker MCP
Powered by Claude Β· Grounded in docs
I know everything about Docker MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
- Build and configure as described above
- Restart Claude Desktop
- 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
- Verify the config file path is correct
- Ensure the binary path in config is absolute
- Check permissions on the binary
- Restart Claude Desktop completely
- Check Claude Desktop logs
Connection errors
- Verify
DOCKER_HOSTis 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)
