# DockerMcpServer

> A Docker MCP Server built using the ModelContextProtocol NuGet package

- **Type:** MCP server
- **Install:** `agentstack add mcp-jamesburton-dockermcpserver`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jamesburton](https://agentstack.voostack.com/s/jamesburton)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jamesburton](https://github.com/jamesburton)
- **Source:** https://github.com/jamesburton/DockerMcpServer

## Install

```sh
agentstack add mcp-jamesburton-dockermcpserver
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Docker MCP Server

A comprehensive Model Context Protocol (MCP) server for Docker operations, providing complete Docker functionality through Claude AI and other MCP clients. Built with .NET 8 and designed for production use.

## Features

This Docker MCP Server provides **complete Docker functionality** that significantly surpasses all existing implementations:

### 🚀 **Container Operations**
- ✅ **Create containers** with full configuration support (35+ options)
- ✅ **Start, stop, restart containers** with timeout controls
- ✅ **Remove containers** with force and volume options
- ✅ **List containers** with advanced filtering and sizing
- ✅ **Get container logs** with timestamps, follow, and filtering
- ✅ **Inspect containers** for detailed information
- ✅ **Execute commands** in running containers
- ✅ **Get real-time statistics** for monitoring

### 🖼️ **Image Operations**
- ✅ **List images** with filtering options
- ✅ **Pull images** from registries with platform support
- ✅ **Remove images** with force options
- ✅ **Build images** from Dockerfiles with build args
- ✅ **Tag images** for repository management
- ✅ **Inspect images** for detailed information
- ✅ **Get image history** and layer information
- ✅ **Prune unused images** with dangling/all options
- ✅ **Search images** in Docker Hub
- ✅ **Push images** to registries

### 🌐 **Network Operations**
- ✅ **List networks** with complete information
- ✅ **Create networks** with custom drivers and IPAM
- ✅ **Remove networks** safely
- ✅ **Connect/disconnect containers** to/from networks
- ✅ **Inspect networks** for configuration details
- ✅ **Prune unused networks**
- ✅ **Subnet configuration** with gateway support

### 💾 **Volume Operations**
- ✅ **List volumes** with filtering
- ✅ **Create volumes** with custom drivers and options
- ✅ **Remove volumes** with force options
- ✅ **Inspect volumes** for detailed information
- ✅ **Prune unused volumes**
- ✅ **Volume filtering** by labels and metadata

### 🐳 **Docker Compose Operations**
- ✅ **Deploy Compose stacks** from YAML with environment injection
- ✅ **Remove Compose stacks** with cleanup options
- ✅ **List Compose stack containers**
- ✅ **Get Compose stack logs** (all services or specific)
- ✅ **Start/stop/restart stacks**
- ✅ **Scale services** in stacks
- ✅ **Execute commands** in Compose services

### 🛠️ **System Operations**
- ✅ **Check Docker availability** and connectivity
- ✅ **Get system information** and capabilities
- ✅ **Get version information** for daemon and API
- ✅ **System-wide pruning** with selective cleanup
- ✅ **Disk usage information** and monitoring
- ✅ **Event monitoring** with filtering
- ✅ **Process information** for containers

### 🎯 **Advanced Container Configuration**
- ✅ **Full volume mount support** (bind mounts, named volumes, tmpfs)
- ✅ **Environment variables** with validation
- ✅ **Port mappings** (multiple ports, TCP/UDP protocols)
- ✅ **Resource limits** (CPU, memory, PID limits)
- ✅ **Security options** (capabilities, AppArmor, SELinux, seccomp)
- ✅ **Device mappings** with permissions
- ✅ **DNS configuration** and custom resolvers
- ✅ **Extra hosts** for /etc/hosts entries
- ✅ **Tmpfs mounts** for temporary filesystems
- ✅ **Ulimits** (file descriptors, processes, memory locks)
- ✅ **Labels and metadata** management
- ✅ **Restart policies** (no, always, unless-stopped, on-failure)
- ✅ **Network modes** (bridge, host, none, container)
- ✅ **User and working directory** specification
- ✅ **Auto-removal support** (--rm equivalent)
- ✅ **Interactive and TTY modes**
- ✅ **Read-only filesystems** for security
- ✅ **Privileged containers** with safety controls

## Installation and Setup

### Prerequisites
- .NET 8.0 SDK or Runtime
- Docker Desktop or Docker Engine
- MCP-compatible client (Claude Desktop, Cursor, VS Code, etc.)

### Option 1: Use Pre-built Binaries (Recommended)

Download the latest release for your platform from [GitHub Releases](https://github.com/jamesburton/DockerMcpServer/releases):

**Windows:**
```bash
# Download and extract Windows x64 version
curl -L https://github.com/jamesburton/DockerMcpServer/releases/latest/download/DockerMcpServer-win-x64.zip -o DockerMcpServer.zip
# Extract and run
```

**Linux:**
```bash
# Download and extract Linux x64 version
curl -L https://github.com/jamesburton/DockerMcpServer/releases/latest/download/DockerMcpServer-linux-x64.tar.gz -o DockerMcpServer.tar.gz
tar -xzf DockerMcpServer.tar.gz
chmod +x DockerMcpServer
./DockerMcpServer
```

**macOS:**
```bash
# Download and extract macOS version (Intel or Apple Silicon)
curl -L https://github.com/jamesburton/DockerMcpServer/releases/latest/download/DockerMcpServer-osx-x64.tar.gz -o DockerMcpServer.tar.gz
tar -xzf DockerMcpServer.tar.gz
chmod +x DockerMcpServer
./DockerMcpServer
```

### Option 2: Use Docker Container

Run the Docker MCP Server in a container using GitHub Container Registry:

```bash
# Basic usage
docker run -d --name docker-mcp-server \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/jamesburton/dockermcpserver:latest

# With custom configuration
docker run -d --name docker-mcp-server \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/config:/app/config \
  ghcr.io/jamesburton/dockermcpserver:latest
```

### Option 3: Run from Source (Development)

1. **Clone the repository:**
```bash
git clone https://github.com/jamesburton/DockerMcpServer.git
cd DockerMcpServer
```

2. **Restore dependencies:**
```bash
dotnet restore
```

3. **Run the server:**
```bash
dotnet run --project DockerMcpServer/DockerMcpServer.csproj
```

## MCP Client Configuration

### Claude Desktop Configuration

Add to your Claude Desktop config file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%/Claude/claude_desktop_config.json`

**Using pre-built executable:**
```json
{
  "mcpServers": {
    "docker": {
      "command": "/path/to/DockerMcpServer",
      "args": [],
      "env": {}
    }
  }
}
```

**Using Docker container:**
```json
{
  "mcpServers": {
    "docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/var/run/docker.sock:/var/run/docker.sock", "ghcr.io/jamesburton/dockermcpserver:latest"],
      "env": {}
    }
  }
}
```

**Using dotnet run (development):**
```json
{
  "mcpServers": {
    "docker": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/DockerMcpServer/DockerMcpServer"],
      "env": {}
    }
  }
}
```

### Cursor Configuration

Similar configuration in your Cursor MCP settings file.

## Usage Examples

### Creating a Container (Qdrant Example)
```
Create a Docker container with:
- Image: qdrant/qdrant:latest
- Name: qdrant
- Auto-remove: true
- Ports: ["6333:6333", "6334:6334"]
- Volumes: ["%cd%/qdrant/storage:/qdrant/storage", "%cd%/qdrant/config:/qdrant/config", "%cd%/qdrant/snapshots:/qdrant/snapshots"]
```

### Advanced Container with Security
```
Create a Docker container with:
- Image: nginx:latest
- Name: secure-nginx
- Memory limit: 512m
- CPU limit: 1.0
- Ports: ["8080:80"]
- User: "1000:1000"
- Read-only: true
- CapDrop: ["ALL"]
- CapAdd: ["NET_BIND_SERVICE"]
- SecurityOpt: ["no-new-privileges", "apparmor:docker-default"]
```

### Deploy a Compose Stack
```
Deploy a Docker Compose stack with:
- Project name: my-app
- Compose YAML: |
  version: '3.8'
  services:
    web:
      image: nginx:latest
      ports:
        - "8080:80"
    db:
      image: postgres:13
      environment:
        POSTGRES_PASSWORD: secret
      volumes:
        - db-data:/var/lib/postgresql/data
  volumes:
    db-data:
```

## Feature Comparison with Existing Solutions

| Feature | **Docker MCP Server** | [QuantGeekDev/docker-mcp](https://github.com/QuantGeekDev/docker-mcp) | [suvarchal/docker-mcp](https://github.com/suvarchal/docker-mcp) | [ckreiling/mcp-server-docker](https://github.com/ckreiling/mcp-server-docker) |
|---------|----------------------|-------------------------|---------------------|---------------------------|
| **Container Creation** | ✅ **35+ options** | ❌ **4 basic options** | ❌ **Basic only** | ❌ **Limited options** |
| **Volume Mounts** | ✅ **Full Support** | ❌ **Not Supported** | ❌ **Not Supported** | ❌ **Basic only** |
| **Auto-removal (--rm)** | ✅ **Supported** | ❌ **Not Supported** | ❌ **Not Supported** | ❌ **Not Supported** |
| **Multiple Port Mappings** | ✅ **TCP/UDP Support** | ✅ **Basic Support** | ✅ **Basic Support** | ✅ **Basic Support** |
| **Environment Variables** | ✅ **With Validation** | ✅ **Basic Support** | ✅ **Basic Support** | ✅ **Basic Support** |
| **Docker Compose** | ✅ **Complete Suite** | ✅ **Deploy/Remove Only** | ❌ **Not Supported** | ❌ **Not Supported** |
| **Network Management** | ✅ **Full CRUD + IPAM** | ❌ **Not Supported** | ❌ **Not Supported** | ❌ **Not Supported** |
| **Volume Management** | ✅ **Full CRUD** | ❌ **Not Supported** | ❌ **Not Supported** | ❌ **Not Supported** |
| **Image Management** | ✅ **Complete Suite** | ❌ **List Only** | ✅ **Basic CRUD** | ❌ **Pull Only** |
| **Resource Limits** | ✅ **CPU/Memory/PID** | ❌ **Not Supported** | ❌ **Not Supported** | ❌ **Not Supported** |
| **Security Options** | ✅ **Capabilities/SELinux/AppArmor** | ❌ **Not Supported** | ❌ **Not Supported** | ❌ **Explicitly Excluded** |
| **Device Mappings** | ✅ **Full Support** | ❌ **Not Supported** | ❌ **Not Supported** | ❌ **Not Supported** |
| **Container Inspection** | ✅ **Complete Details** | ❌ **Not Supported** | ❌ **Not Supported** | ❌ **Not Supported** |
| **Real-time Stats** | ✅ **CPU/Memory/Network** | ❌ **Not Supported** | ❌ **Not Supported** | ❌ **Not Supported** |
| **System Information** | ✅ **Full System API** | ❌ **Not Supported** | ❌ **Not Supported** | ❌ **Not Supported** |
| **Container Logs** | ✅ **Advanced Filtering** | ✅ **Basic Support** | ❌ **Not Supported** | ❌ **Not Supported** |
| **Container Exec** | ✅ **Interactive Support** | ❌ **Not Supported** | ❌ **Not Supported** | ❌ **Not Supported** |
| **System Cleanup** | ✅ **Comprehensive Pruning** | ❌ **Not Supported** | ❌ **Not Supported** | ❌ **Not Supported** |
| **Platform** | 🟢 **.NET 8** | 🐍 **Python** | 🟨 **Node.js** | 🐍 **Python** |
| **Architecture** | 🏗️ **Modular/Enterprise** | 📝 **Simple Script** | 📝 **Basic CLI Wrapper** | 📝 **Simple Script** |

### Competitor Analysis

#### [QuantGeekDev/docker-mcp](https://github.com/QuantGeekDev/docker-mcp)
- **Scope**: Basic container and Compose operations
- **Limitations**: No volume management, network operations, security features, or system monitoring
- **Architecture**: Python-based simple implementation

#### [suvarchal/docker-mcp](https://github.com/suvarchal/docker-mcp)
- **Scope**: Basic container and image operations
- **Limitations**: No Compose support, no advanced features, CLI wrapper approach
- **Architecture**: Node.js with Docker CLI dependency

#### [ckreiling/mcp-server-docker](https://github.com/ckreiling/mcp-server-docker)
- **Scope**: Limited container operations with safety restrictions
- **Limitations**: Explicitly excludes security features, no Compose/network/volume support
- **Architecture**: Python with safety-first approach

## Architecture

### Core Components

- **`IDockerService`**: Main service interface for all Docker operations
- **`DockerService`**: Comprehensive implementation using Docker.DotNet API
- **`DockerClientFactory`**: Factory for creating and configuring Docker clients
- **Model Classes**: Strongly-typed request/response models with validation

### Modular Design (Partial Classes)

- **`DockerService.Container.cs`**: Container lifecycle management
- **`DockerService.Image.cs`**: Image operations and registry interactions
- **`DockerService.Volume.cs`**: Volume management and storage operations
- **`DockerService.Network.cs`**: Network creation and management
- **`DockerService.Compose.cs`**: Docker Compose stack operations
- **`DockerService.System.cs`**: System-level operations and monitoring
- **`DockerService.Security.cs`**: Security validation and enforcement
- **`DockerService.Helpers.cs`**: Utility methods and parsers

### MCP Command Classes

- **`DockerContainerCommands`**: 11 container management tools
- **`DockerImageCommands`**: 10 image operation tools
- **`DockerNetworkCommands`**: 8 network management tools
- **`DockerVolumeCommands`**: 5 volume operation tools
- **`DockerComposeCommands`**: 7 Compose stack tools
- **`DockerSystemCommands`**: 8 system maintenance tools

**Total: 49+ MCP tools** providing comprehensive Docker functionality

## Dependencies

- **Microsoft.Extensions.Hosting** (8.0.1): Application hosting framework
- **Microsoft.Extensions.Logging** (8.0.1): Structured logging infrastructure
- **ModelContextProtocol** (0.1.0-preview.11): MCP server implementation
- **Docker.DotNet** (3.125.15): Official Docker API client for .NET
- **YamlDotNet** (16.2.1): YAML parsing for Compose files

## Development and Debugging

### MCP Inspector

For development and debugging, use the MCP Inspector:

```bash
# For source-based development
npx @modelcontextprotocol/inspector dotnet run --project /path/to/DockerMcpServer/DockerMcpServer

# For built executable
npx @modelcontextprotocol/inspector /path/to/DockerMcpServer
```

### Logging

The server includes comprehensive logging with different levels:
- **Information**: Successful operations and state changes
- **Warning**: Non-critical issues and fallbacks
- **Error**: Operation failures with detailed context
- **Debug**: Detailed operation traces (development only)

Logs are output to stderr to avoid interfering with MCP communication.

## CI/CD Pipeline

### Automated Builds and Releases

This repository includes a comprehensive CI/CD pipeline that automatically:

- ✅ **Tests** code on every push and pull request
- ✅ **Builds** multi-platform binaries (Windows, Linux, macOS - x64, ARM64)
- ✅ **Creates** Docker images for linux/amd64 and linux/arm64
- ✅ **Publishes** to GitHub Container Registry (ghcr.io)
- ✅ **Generates** GitHub releases with downloadable assets

### Required Setup for Contributors

To enable Docker image publishing, repository maintainers need to configure:

1. **GHCR_TOKEN Secret**: Personal Access Token with `write:packages` scope
   - See [docs/CI-CD-SETUP.md](docs/CI-CD-SETUP.md) for detailed instructions

2. **Optional**: Configure additional secrets for extended functionality as needed

### Triggering Releases

```bash
# Create and push a new version tag
git tag v1.0.x
git push origin v1.0.x
```

This automatically triggers the full CI/CD pipeline and creates a GitHub release.

## Docker Images

Docker images are available on GitHub Container Registry:

- **Latest version**: `docker pull ghcr.io/jamesburton/dockermcpserver:latest`
- **Specific version**: `docker pull ghcr.io/jamesburton/dockermcpserver:v1.0.1`

### Image Features
- Multi-platform support (linux/amd64, linux/arm64)
- Non-root user for security
- Health checks included
- Minimal attack surface
- Docker CLI included for Docker-in-Docker scenarios

## Error Handling

The server includes production-grade error handling:
- **Docker daemon connectivity**: Automatic connection retry and clear error messages
- **Invalid configurations**: Parameter validation with helpful error descriptions
- **Resource conflicts**: Graceful handling of naming conflicts and resource locks
- **Permission errors**: Clear guidance on Docker daemon access requirements
- **Network timeouts**: Configurable timeouts with retry logic

All errors are returned as structured `CommandResult` objects with:
- Success/failure status
- Descriptive error messages
- Error context and troubleshooting hints
- Operation-specific data when available

## Security Considerations

### Container Security
- **Default non-privileged**: Containers run without elevated privileges by default
- **Capability management**: Precise control over Linux capabilities
- **Security contexts**: Support for AppArmor,

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jamesburton](https://github.com/jamesburton)
- **Source:** [jamesburton/DockerMcpServer](https://github.com/jamesburton/DockerMcpServer)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jamesburton-dockermcpserver
- Seller: https://agentstack.voostack.com/s/jamesburton
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.