🐋 MCP Server Docker (NPX Package)

A powerful Model Context Protocol (MCP) server for Docker management with NPX support. Control Docker containers, images, networks, and volumes using natural language through Claude and other MCP-compatible AI clients.

🚀 Quick Start

# Run directly with npx (no installation needed)
npx mcp-server-docker-npx

# Or install globally
npm install -g mcp-server-docker-npx
mcp-server-docker

✨ Features

• 🐳 21 Docker Tools: Complete container, image, network, and volume management
• 🔌 Docker Socket Access: Auto-detection and mounting for Docker-in-Docker scenarios
• 🌐 Remote Docker Support: SSH, TCP, and socket connections
• 🎯 Natural Language Interface: Use with Claude Desktop and other MCP clients
• 🖥️ Cross-Platform: Works on macOS, Linux, and Windows
• 📦 Zero Configuration: Auto-detects Docker installations and sockets

🛠️ Installation Options

Option 1: NPX (Recommended)

npx mcp-server-docker-npx --help

Option 2: Global Install

npm install -g mcp-server-docker-npx
mcp-server-docker --help

Option 3: Python Backend (Required)

# Install the Python MCP server backend
pip install mcp-server-docker

# Or with uv
uv tool install mcp-server-docker

🔧 Claude Desktop Configuration

Add this to your Claude Desktop MCP configuration:

Local Docker

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

Remote Docker (SSH)

{
  "mcpServers": {
    "docker-remote": {
      "command": "npx",
      "args": ["mcp-server-docker-npx", "--docker-host", "ssh://user@hostname"]
    }
  }
}

Remote Docker (TCP)

{
  "mcpServers": {
    "docker-tcp": {
      "command": "npx",
      "args": ["mcp-server-docker-npx"],
      "env": {
        "DOCKER_HOST": "tcp://192.168.1.100:2376"
      }
    }
  }
}

🛠️ Available Tools

📦 Containers (9 tools)

• list_containers - List all Docker containers
• create_container - Create a new container
• run_container - Run an image in a new container
• run_container_with_socket - 🆕 Run container with Docker socket access
• recreate_container - Stop, remove, and recreate a container
• start_container - Start a stopped container
• stop_container - Stop a running container
• remove_container - Remove a container
• fetch_container_logs - Get container logs

💿 Images (4 tools)

• list_images - List Docker images
• pull_image - Pull an image from registry
• push_image - Push an image to registry
• build_image - Build image from Dockerfile
• remove_image - Remove an image

🌐 Networks (3 tools)

• list_networks - List Docker networks
• create_network - Create a Docker network
• remove_network - Remove a Docker network

💾 Volumes (3 tools)

• list_volumes - List Docker volumes
• create_volume - Create a Docker volume
• remove_volume - Remove a Docker volume

🔍 System & Socket (3 tools)

• docker_socket_info - 🆕 Get Docker socket information
• docker_system_info - 🆕 Get detailed system information
• docker_compose - Natural language container orchestration

🌐 Remote Docker Examples

SSH Connection

# Connect to remote Docker via SSH
npx mcp-server-docker-npx --docker-host ssh://[email protected]

# With environment variable
DOCKER_HOST=ssh://user@hostname npx mcp-server-docker-npx

TCP Connection

# Connect via TCP
npx mcp-server-docker-npx --docker-host tcp://192.168.1.100:2376

# With TLS
DOCKER_HOST=tcp://hostname:2376 DOCKER_TLS_VERIFY=1 npx mcp-server-docker-npx

🔌 Docker Socket Features

Auto-Detection

The server automatically detects Docker sockets on your system:

• Linux: /var/run/docker.sock, /run/docker.sock
• macOS: Docker Desktop, Colima, and standard locations
• Windows: Named pipes for Docker Desktop

Docker-in-Docker

# Run a container with Docker socket access
# This allows the container to control the Docker daemon
run_container_with_socket:
  image: "docker:latest"
  mount_docker_socket: true
  command: ["docker", "ps"]

🚨 Security Considerations

• Docker Socket Access: Mounting the Docker socket gives full control over the Docker daemon
• Remote Connections: Use SSH keys for authentication when connecting remotely
• Container Permissions: Review containers before running, especially with socket access

📚 Environment Variables

• DOCKER_HOST - Docker daemon host URL
• MCP_SERVER_DOCKER_HOST - Override Docker host for MCP server
• DOCKER_TLS_VERIFY - Enable TLS verification
• DOCKER_CERT_PATH - Path to TLS certificates
• MCP_SERVER_AUTO_DETECT_SOCKET - Enable/disable socket auto-detection

🧪 Testing

# Test the NPX wrapper
npm test

# Test Python backend installation
npm run install-python

# Test with remote Docker
npx mcp-server-docker-npx --docker-host ssh://user@hostname

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with npm test
5. Submit a pull request

📝 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub: mcp-server-docker
• NPM Package: mcp-server-docker-npx
• MCP Protocol: Model Context Protocol
• Claude Desktop: Anthropic Claude

📊 Stats

• 21 Docker Tools available
• Cross-platform support (macOS, Linux, Windows)
• Auto-detection of Docker installations
• Remote Docker support via SSH/TCP
• Docker-in-Docker capabilities

Made with ❤️ for the MCP community