Docker MCP

Docker MCP Server

Powerful Docker management for AI assistants

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)

npx @alisaitteke/docker-mcp

Local Installation

npm install -g @alisaitteke/docker-mcp

Or install locally in your project:

npm install @alisaitteke/docker-mcp

Quick Start

With Cursor

1. Add to your Cursor MCP configuration (usually in .cursor/mcp.json or similar):

{

"mcpServers": { "docker": { "command": "npx", "args": ["@alisaitteke/docker-mcp"] } } }

1. 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

{

"mcpServers": { "docker": { "command": "npx", "args": ["@alisaitteke/docker-mcp"] } } }

1. 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:

git clone <repository-url>

cd docker-mcp

1. Install dependencies:

npm install

1. Build the project:

npm run build

Running Locally

Method 1: Using npm start (after build)

# Build first

npm run build

Run the server

npm start

Method 2: Using npm run dev (development mode with tsx)

npm run dev

This uses tsx to run TypeScript directly without building.

Method 3: Direct execution

# Build first

npm run build

Run directly with node

node dist/index.js

Method 4: Using the binary

# 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:

npm run build

1. Test the changes:

npm start

or

npm run dev

4. Check for TypeScript errors:

npm run typecheck

1. Lint the code:

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)

1. 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:

# 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:

# 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