# Docker MCP Server
<div align="center">
<img src="https://raw.githubusercontent.com/alisaitteke/docker-mcp/develop/social_preview.png" alt="Docker MCP Server" width="600"/>
</div>
<div align="center">
**Powerful Docker management for AI assistants**
[](https://www.npmjs.com/package/@alisaitteke/docker-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
</div>
A comprehensive Model Context Protocol (MCP) server that empowers AI assistants like Cursor, Claude Desktop, and other MCP-compatible clients to seamlessly manage Docker containers, images, networks, volumes, and registries through natural language interactions.
## ✨ Why Docker MCP Server?
- 🚀 **Zero Configuration** - Works out of the box with `npx`, no installation needed
- 🔒 **Safety First** - Two-step confirmation for destructive operations
- 🌐 **Cross-Platform** - Works on Windows, Linux, and macOS with automatic Docker socket detection
- 🎯 **Comprehensive** - Full Docker API coverage including Compose, registries, and system operations
- 🤖 **AI-Native** - Designed specifically for AI assistants with clear, structured responses
## 🎯 Features
### 🐳 Container Management
- **Full lifecycle control**: Create, start, stop, restart, kill, and remove containers
- **Monitoring**: Real-time logs, statistics, and container inspection
- **Advanced operations**: Pause/unpause, exec commands, and resource management
### 🖼️ Image Management
- **Registry operations**: Pull, push, tag, and remove images
- **Build support**: Build images from Dockerfiles with full configuration
- **Inspection**: Detailed image history, layers, and metadata
### 🌐 Network Management
- **Network operations**: Create, remove, and inspect Docker networks
- **Container connectivity**: Connect/disconnect containers from networks
- **Network discovery**: List and filter networks with advanced options
### 💾 Volume Management
- **Volume operations**: Create, remove, and inspect volumes
- **Data persistence**: Manage persistent storage for containers
- **Volume inspection**: Detailed volume information and mount points
### ⚙️ System Operations
- **System information**: Docker daemon info, version, and capabilities
- **Resource cleanup**: Prune unused images, containers, volumes, and networks
- **Event monitoring**: Real-time Docker event stream
### 🔧 Container Execution
- **Command execution**: Run commands in running containers
- **Interactive sessions**: Create and manage exec instances
- **Output streaming**: Real-time command output and logs
### 📦 Registry Integration
- **Docker Hub**: Search repositories, list tags, authenticate, pull/push images
- **GitHub Container Registry (GHCR)**: Full authentication and image management
- **Multi-registry support**: Seamlessly work with multiple registries
### 🎼 Docker Compose Support
- **Multi-container management**: Start, stop, restart compose services
- **Service monitoring**: View logs and status of compose services
- **Build operations**: Build compose services with dependency management
- **Configuration validation**: Parse and validate docker-compose.yml files
### 🛡️ Safety Features
- **Two-step confirmation** for all destructive operations
- **Resource preview**: See what will be deleted before confirmation
- **Dual confirmation methods**:
- **Confirm parameter** (default): Works everywhere, simple and reliable
- **MCP Elicitation API** (advanced): Interactive form-based confirmation for better UX
## Installation
### Via npx (Recommended)
```bash
npx @alisaitteke/docker-mcp
```
### Local Installation
```bash
npm install -g @alisaitteke/docker-mcp
```
Or install locally in your project:
```bash
npm install @alisaitteke/docker-mcp
```
## Quick Start
### With Cursor
1. Add to your Cursor MCP configuration (usually in `.cursor/mcp.json` or similar):
```json
{
"mcpServers": {
"docker": {
"command": "npx",
"args": ["@alisaitteke/docker-mcp"]
}
}
}
```
2. Restart Cursor and start managing Docker with AI!
### With Claude Desktop
1. Add to your Claude Desktop configuration:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"docker": {
"command": "npx",
"args": ["@alisaitteke/docker-mcp"]
}
}
}
```
2. Restart Claude Desktop and start managing Docker with AI!
## Local Development and Testing
### Prerequisites
- Node.js 18.0.0 or higher
- Docker daemon running
- npm or yarn
### Setup
1. Clone the repository:
```bash
git clone <repository-url>
cd docker-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
### Running Locally
#### Method 1: Using npm start (after build)
```bash
# Build first
npm run build
# Run the server
npm start
```
#### Method 2: Using npm run dev (development mode with tsx)
```bash
npm run dev
```
This uses `tsx` to run TypeScript directly without building.
#### Method 3: Direct execution
```bash
# Build first
npm run build
# Run directly with node
node dist/index.js
```
#### Method 4: Using the binary
```bash
# Build first
npm run build
# Make sure the binary is executable
chmod +x bin/docker-mcp-server.js
# Run the binary
./bin/docker-mcp-server.js
```
### Development Workflow
1. Make changes to source files in `src/`
2. Build the project:
```bash
npm run build
```
3. Test the changes:
```bash
npm start
# or
npm run dev
```
4. Check for TypeScript errors:
```bash
npm run typecheck
```
5. Lint the code:
```bash
npm run lint
```
### Troubleshooting
**Docker connection issues:**
- Ensure Docker daemon is running: `docker ps`
- **Linux/macOS**: Check Docker socket permissions: `ls -la /var/run/docker.sock`
- **Windows**: Ensure Docker Desktop is running and named pipe is accessible
- For remote Docker, set environment variables: `DOCKER_HOST`, `DOCKER_CERT_PATH`, etc.
- **macOS**: If `/var/run/docker.sock` doesn't exist, try `~/.docker/run/docker.sock` (Docker Desktop 4.0+)
**Build errors:**
- Clear node_modules and reinstall: `rm -rf node_modules && npm install`
- Check TypeScript version compatibility
- Ensure all dependencies are installed: `npm install`
**Runtime errors:**
- Check that Docker is accessible: `docker version`
- Verify the build was successful: `ls -la dist/`
- Check server logs (errors are written to stderr)
## Configuration
The server automatically detects the operating system and uses the appropriate Docker socket path:
### Platform-Specific Defaults
- **Linux**: `/var/run/docker.sock` (Unix socket)
- **macOS**: `/var/run/docker.sock` or `~/.docker/run/docker.sock` (Docker Desktop 4.0+)
- **Windows**: `//./pipe/docker_engine` (Named pipe)
### Connection Methods (in order of priority)
1. **Environment variables** (highest priority):
- `DOCKER_HOST` - Docker daemon host (e.g., `tcp://localhost:2376`, `npipe:////./pipe/docker_engine`)
- `DOCKER_PORT` - Docker daemon port
- `DOCKER_PROTOCOL` - Protocol (`http` or `https`)
- `DOCKER_SOCKET_PATH` - Path to Docker socket (overrides platform default)
- `DOCKER_CERT_PATH` - Path to Docker certificates directory
- `DOCKER_TLS_VERIFY` - Enable TLS verification (`1` or `0`)
2. **Platform-specific defaults** (automatic detection):
- Linux: `/var/run/docker.sock`
- macOS: `/var/run/docker.sock` (or `~/.docker/run/docker.sock` if available)
- Windows: `//./pipe/docker_engine`
### Windows Configuration
On Windows, Docker Desktop uses named pipes. The server automatically detects Windows and uses the correct path. You can also explicitly set:
```bash
# Using environment variable
set DOCKER_SOCKET_PATH=//./pipe/docker_engine
# Or using DOCKER_HOST
set DOCKER_HOST=npipe:////./pipe/docker_engine
```
### Remote Docker Host
To connect to a remote Docker host:
```bash
# Linux/macOS
export DOCKER_HOST=tcp://192.168.1.100:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=/path/to/certs
# Windows
set DOCKER_HOST=tcp://192.168.1.100:2376
set DOCKER_TLS_VERIFY=1
set DOCKER_CERT_PATH=C:\path\to\certs
```
## Available Tools
### Container Tools
- `docker_list_containers` - List all containers
- `docker_create_container` - Create a new container
- `docker_start_container` - Start a container
- `docker_stop_container` - Stop a container
- `docker_restart_container` - Restart a container
- `docker_kill_container` - Kill a container
- `docker_remove_container` - Remove a container
- `docker_inspect_container` - Get container details
- `docker_container_logs` - Get container logs
- `docker_container_stats` - Get container statistics
- `docker_pause_container` - Pause a container
- `docker_unpause_container` - Unpause a container
### Image Tools
- `docker_list_images` - List all images
- `docker_pull_image` - Pull an image from registry
- `docker_push_image` - Push an image to registry
- `docker_tag_image` - Tag an image
- `docker_remove_image` - Remove an image
- `docker_inspect_image` - Get image details
- `docker_image_history` - Get image history
### Network Tools
- `docker_list_networks` - List all networks
- `docker_create_network` - Create a network
- `docker_remove_network` - Remove a network
- `docker_inspect_network` - Get network details
- `docker_connect_container` - Connect container to network
- `docker_disconnect_container` - Disconnect container from network
### Volume Tools
- `docker_list_volumes` - List all volumes
- `docker_create_volume` - Create a volume
- `docker_remove_volume` - Remove a volume
- `docker_inspect_volume` - Get volume details
### System Tools
- `docker_system_info` - Get Docker system information
- `docker_version` - Get Docker version
- `docker_prune_system` - Prune all unused resources
- `docker_prune_images` - Prune unused images
- `docker_prune_containers` - Prune stopped containers
- `docker_prune_volumes` - Prune unused volumes
- `docker_prune_networks` - Prune unused networks
### Exec Tools
- `docker_exec` - Execute a command in a container
- `docker_inspect_exec` - Get exec instance details
### Compose Tools
- `docker_compose_up` - Start Docker Compose services
- `docker_compose_down` - Stop and remove Docker Compose services
- `docker_compose_ps` - List Docker Compose services
- `docker_compose_logs` - View output from Docker Compose services
- `docker_compose_config` - Parse and validate docker-compose.yml file
- `docker_compose_build` - Build Docker Compose services
- `docker_compose_restart` - Restart Docker Compose services
- `docker_compose_stop` - Stop Docker Compose services
- `docker_compose_start` - Start Docker Compose services
### Registry Tools
- `dockerhub_search` - Search Docker Hub
- `dockerhub_get_tags` - Get repository tags from Docker Hub
- `dockerhub_authenticate` - Authenticate with Docker Hub
- `dockerhub_pull` - Pull from Docker Hub
- `dockerhub_push` - Push to Docker Hub
- `ghcr_authenticate` - Authenticate with GitHub Container Registry
- `ghcr_pull` - Pull from GHCR
- `ghcr_push` - Push to GHCR
## Examples
### List running containers
```json
{
"name": "docker_list_containers",
"arguments": {
"all": false
}
}
```
### Create and start a container
```json
{
"name": "docker_create_container",
"arguments": {
"image": "nginx:latest",
"name": "my-nginx",
"ports": {"80/tcp": {}}
}
}
```
Then start it:
```json
{
"name": "docker_start_container",
"arguments": {
"id": "my-nginx"
}
}
```
### Pull an image from Docker Hub
```json
{
"name": "docker_pull_image",
"arguments": {
"name": "ubuntu:20.04"
}
}
```
### Search Docker Hub
```json
{
"name": "dockerhub_search",
"arguments": {
"query": "node",
"limit": 10
}
}
```
### Execute a command in a container
```json
{
"name": "docker_exec",
"arguments": {
"containerId": "my-container",
"cmd": ["ls", "-la"],
"tty": false
}
}
```
### Start Docker Compose services
```json
{
"name": "docker_compose_up",
"arguments": {
"projectDir": "/path/to/compose/project",
"detach": true,
"build": true
}
}
```
### View Compose logs
```json
{
"name": "docker_compose_logs",
"arguments": {
"projectDir": "/path/to/compose/project",
"follow": false,
"tail": 100
}
}
```
### Removing Resources with Confirmation
All destructive operations (remove, kill, prune) support two confirmation methods:
#### Method 1: Confirm Parameter (Default - Works Everywhere)
**Step 1: Preview (without confirm)**
```json
{
"name": "docker_remove_volume",
"arguments": {
"name": "my-volume"
}
}
```
This returns volume details and a warning message.
**Step 2: Confirm (with confirm=true)**
```json
{
"name": "docker_remove_volume",
"arguments": {
"name": "my-volume",
"confirm": true
}
}
```
This actually removes the volume.
#### Method 2: MCP Elicitation API (Advanced - Better UX)
If your MCP client (Cursor, Claude Desktop) supports Elicitation API, you can use interactive confirmation:
```json
{
"name": "docker_remove_volume",
"arguments": {
"name": "my-volume",
"useElicitation": true
}
}
```
This will show an interactive confirmation dialog in the client (if supported). The client will display a form asking for confirmation, and the operation proceeds only if the user accepts.
**Note:** Elicitation API support depends on the MCP client. If the client doesn't support it, the server automatically falls back to the `confirm` parameter method.
**Operations requiring confirmation:**
- `docker_remove_volume` - Remove volumes
- `docker_remove_container` - Remove containers
- `docker_kill_container` - Kill containers
- `docker_remove_image` - Remove images
- `docker_remove_network` - Remove networks
- `docker_prune_system` - Prune all unused resources
- `docker_prune_images` - Prune unused images
- `docker_prune_containers` - Prune stopped containers
- `docker_prune_volumes` - Prune unused volumes
- `docker_prune_networks` - Prune unused networks
## Testing the Server
### Quick Test
1. Build the project:
```bash
npm run build
```
2. Use the test script:
```bash
./test-server.sh
```
Or test manually:
3. Test Docker connection:
```bash
# The server will exit with error if Docker is not accessible
node dist/index.js
```
If Docker is running, you should see:
```
Docker MCP Server running on stdio
```
4. Test with a simple MCP request (using jq for JSON formatting):
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js | jq
```
**Note:** The server communicates via stdio, so it will wait for JSON-RPC requests. Press Ctrl+C to exit.
### Manual Testing Steps
1. **Start the server:**
```bash
npm run build
npm start
```
2. **In another terminal, test with curl (if using HTTP transport) or use an MCP client**
3. **Verify Docker operations work:**
- List containers: Use `docker_list_containers` tool
- Check system info: Use `docker_system_info` tool
### Integration Testing
For full integration testing, you'll need an MCP client. The server communicates via stdio (standard input/output), so it's designed to work with MCP-compatible clients like:
- Cursor IDE
- Claude Desktop
- Custom MCP clients
### Debugging
Enable verbose logging by checking stderr output. The server writes errors and status messages to stderr:
```bash
# Run and capture stderr
node dist/index.js 2> debug.log
```
## Requirements
- Node.js 18.0.0 or higher
- Docker daemon running and accessible
- **Supported Platforms:**
- Linux (x64, ARM64)
- macOS (Intel, Apple Silicon)
- Windows (x64, ARM64)
- For remote Docker: Proper network access and TLS certificates (if using TLS)
### Platform-Specific Notes
- **Linux**: Requires Docker daemon with Unix socket at `/var/run/docker.sock`
- **macOS**: Works with Docker Desktop. Automatically detects socket location.
- **Windows**: Works with Docker Desktop. Uses named pipe `//./pipe/docker_engine`
## Quick Start (Local Development)
```bash
# Clone and setup
git clone <repository-url>
cd docker-mcp
npm install
# Build
npm run build
# Test
./test-server.sh
# Run
npm start
# or for development
npm run dev
```
## License
MIT
## Testing with MCP Clients
### Testing with Cursor (Local Development)
If you're developing locally and want to test with Cursor:
1. Build the project:
```bash
npm run build
```
2. Add to Cursor MCP configuration (usually in `.cursor/mcp.json` or similar):
```json
{
"mcpServers": {
"docker": {
"command": "node",
"args": ["/absolute/path/to/docker-mcp/dist/index.js"]
}
}
}
```
Or if using the binary:
```json
{
"mcpServers": {
"docker": {
"command": "/absolute/path/to/docker-mcp/bin/docker-mcp-server.js"
}
}
}
```
### Testing with Claude Desktop (Local Development)
If you're developing locally and want to test with Claude Desktop:
1. Build the project:
```bash
npm run build
```
2. Add to Claude Desktop configuration:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"docker": {
"command": "node",
"args": ["/absolute/path/to/docker-mcp/dist/index.js"]
}
}
}
```
### Testing with MCP Inspector (CLI)
You can test the server using MCP Inspector or any MCP client:
```bash
# Build first
npm run build
# The server communicates via stdio, so you can pipe commands to it
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
