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"]
    }
  }
}

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

{
  "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:

git clone <repository-url>
cd docker-mcp

2. Install dependencies:

npm install

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

3. Test the changes:

npm start
# or
npm run dev

4. Check for TypeScript errors:

npm run typecheck

5. 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)

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:

# 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

• 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

{
  "name": "docker_list_containers",
  "arguments": {
    "all": false
  }
}

Create and start a container

{
  "name": "docker_create_container",
  "arguments": {
    "image": "nginx:latest",
    "name": "my-nginx",
    "ports": {"80/tcp": {}}
  }
}

Then start it:

{
  "name": "docker_start_container",
  "arguments": {
    "id": "my-nginx"
  }
}

Pull an image from Docker Hub

{
  "name": "docker_pull_image",
  "arguments": {
    "name": "ubuntu:20.04"
  }
}

Search Docker Hub

{
  "name": "dockerhub_search",
  "arguments": {
    "query": "node",
    "limit": 10
  }
}

Execute a command in a container

{
  "name": "docker_exec",
  "arguments": {
    "containerId": "my-container",
    "cmd": ["ls", "-la"],
    "tty": false
  }
}

Start Docker Compose services

{
  "name": "docker_compose_up",
  "arguments": {
    "projectDir": "/path/to/compose/project",
    "detach": true,
    "build": true
  }
}

View Compose logs

{
  "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)

{
  "name": "docker_remove_volume",
  "arguments": {
    "name": "my-volume"
  }
}

This returns volume details and a warning message.

Step 2: Confirm (with confirm=true)

{
  "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:

{
  "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:

npm run build

2. Use the test script:

./test-server.sh

Or test manually:

3. Test Docker connection:

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

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:

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:

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

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

npm run build

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

{
  "mcpServers": {
    "docker": {
      "command": "node",
      "args": ["/absolute/path/to/docker-mcp/dist/index.js"]
    }
  }
}

Or if using the binary:

{
  "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:

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

{
  "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:

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