io.github.alisaitteke/docker-mcp

MCP server for managing Docker containers, images, networks, volumes, and registries

Open source Open in the app JSON README (API)

About

MCP server for managing Docker containers, images, networks, volumes, and registries

Details

Kind

MCP servers

Topic

Cloud & DevOps

Publisher

alisaitteke

Origin

official

Category

ferramentas

Transport

local

Version

0.2.4

Stars

2

Last push

2026-01-27T21:32:14Z

Repository state

ativo

Language

TypeScript

Added

2026-08-29 03:02:24

Updated

2026-08-29 03:02:24

Origin id

io.github.alisaitteke/docker-mcp

README

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

[![npm version](https://img.shields.io/npm/v/@alisaitteke/docker-mcp.svg)](https://www.npmjs.com/package/@alisaitteke/docker-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](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

## <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/star-white.svg"><img src="docs/icons/star.svg" width="24" height="24" alt="Features"></picture> 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

## <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/package-white.svg"><img src="docs/icons/package.svg" width="24" height="24" alt="Installation"></picture> 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
```

## <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/rocket-white.svg"><img src="docs/icons/rocket.svg" width="24" height="24" alt="Quick Start"></picture> 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)

## <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/gear-white.svg"><img src="docs/icons/gear.svg" width="24" height="24" alt="Configuration"></picture> 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
```

## <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/wrench-white.svg"><img src="docs/icons/wrench.svg" width="24" height="24" alt="Available Tools"></picture> 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

## <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/document-white.svg"><img src="docs/icons/document.svg" width="24" height="24" alt="Examples"></picture> 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
```

## <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/checklist-white.svg"><img src="docs/icons/checklist.svg" width="24" height="24" alt="Requirements"></picture> 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
```

## <picture><source media="(prefers-color-scheme: dark)" srcset="docs/icons/handshake-white.svg"><img src="docs/icons/handshake.svg" width="24" height="24" alt="Contributing"></picture> Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

More

• More mcp servers on Cloud & DevOps
• Everything published by alisaitteke
• Browse the whole catalog