@thelord/mcp-server-docker-npx/README.md

🐋 Docker MCP Server with NPX support - Manage Docker containers, images, networks, and volumes with natural language. Includes Docker socket access and remote Docker support via SSH/TCP.

# 🐋 MCP Server Docker (NPX Package)

[![npm version](https://badge.fury.io/js/mcp-server-docker-npx.svg)](https://badge.fury.io/js/mcp-server-docker-npx)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
# 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)
```bash
npx mcp-server-docker-npx --help
```

### Option 2: Global Install
```bash
npm install -g mcp-server-docker-npx
mcp-server-docker --help
```

### Option 3: Python Backend (Required)
```bash
# 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
```json
{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["mcp-server-docker-npx"]
    }
  }
}
```

### Remote Docker (SSH)
```json
{
  "mcpServers": {
    "docker-remote": {
      "command": "npx",
      "args": ["mcp-server-docker-npx", "--docker-host", "ssh://user@hostname"]
    }
  }
}
```

### Remote Docker (TCP)
```json
{
  "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
```bash
# Connect to remote Docker via SSH
npx mcp-server-docker-npx --docker-host ssh://root@10.10.10.202

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

### TCP Connection
```bash
# 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
```bash
# 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

```bash
# 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](LICENSE) file for details.

## 🔗 Links

- **GitHub**: [mcp-server-docker](https://github.com/ckreiling/mcp-server-docker)
- **NPM Package**: [mcp-server-docker-npx](https://www.npmjs.com/package/mcp-server-docker-npx)
- **MCP Protocol**: [Model Context Protocol](https://modelcontextprotocol.io)
- **Claude Desktop**: [Anthropic Claude](https://claude.ai)

## 📊 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**