williajm/mcp_docker

MCP Docker Server

Category	Status
Build & CI
SonarQube
Security
Package
Technology

A Model Context Protocol (MCP) server that exposes Docker functionality to AI assistants like Claude. Manage containers, images, networks, and volumes through a type-safe, documented API with safety controls.

Quick Start:

• Claude Code (stdio): claude mcp add --transport stdio docker uvx mcp-docker@latest
• Codex (stdio): codex mcp add docker -- uvx mcp-docker@latest

Features

• 33 Docker Tools: Individually optional via config. Complete container, image, network, volume, and system management
• 5 AI Prompts: Intelligent troubleshooting, optimization, networking debug, and security analysis
• 2 Resource Templates: Parameterized access to container logs and stats (via resources/templates/list)
• 2 Transport Options: stdio (local) and HTTP (network deployments)
• Type Safety: Full type hints with Pydantic validation and mypy strict mode
• Safety Controls: Three-tier safety system (safe/moderate/destructive) with configurable restrictions
• Comprehensive Testing: Extensive test coverage with unit, integration, E2E, and fuzz tests
• Continuous Fuzzing: ClusterFuzzLite integration for security and robustness (OpenSSF Scorecard compliant)
• Modern Python: Built with Python 3.11+, uv package manager, and async-first design

Install Instructions

Prerequisites

• Python 3.11+ and Docker installed
• uv package manager (automatically installed by uvx)

Installation with Claude Code

Run this command in your terminal:

claude mcp add --transport stdio docker uvx mcp-docker@latest

That's it! The Docker socket is auto-detected for your OS (Windows, Linux, macOS, WSL).

Installation with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "docker": {
      "command": "uvx",
      "args": ["mcp-docker"]
    }
  }
}

Note: No additional configuration needed for local use. The Docker socket is automatically detected based on your operating system.

Getting Updates: uvx caches packages and won't automatically update. To get the latest version:

# Run the latest version (recommended - no caching)
uvx mcp-docker@latest

# Or clear all cached tool environments
uv cache prune

Advanced Usage

HTTP Transport

For network-accessible deployments, use HTTP transport:

# Run with HTTP transport
mcp-docker --transport http --host 127.0.0.1 --port 8000

Production Deployment:

For production use, deploy behind a reverse proxy (NGINX, Caddy) that provides:

• HTTPS/TLS termination
• OAuth/authentication
• Rate limiting
• IP filtering

Command-line options: --transport (stdio/http), --host, --port

Security

The MCP Docker server provides security for production deployments with rate limiting, audit logging, and safety controls.

⚠️ Important: Container logs may contain malicious prompts (RADE risk). See for threat model and mitigations.

For production deployment, see for:

• Complete security feature guide (OAuth, TLS, IP filtering, rate limiting, audit logging)
• Production deployment checklist
• Threat model and mitigation strategies
• Security best practices

Configuration

All environment variables (safety, server, transports, OAuth, rate limits, CORS) are documented in . Production hardening steps, threat models, and deployment checklists live in .

Documentation:

• - Complete configuration reference (all options)
• - Security features and production guidelines

Tools Overview

The server provides 33 tools organized into 5 categories:

Container Management (10 tools)

• docker_list_containers - List containers with filters
• docker_inspect_container - Get detailed container info
• docker_create_container - Create new container
• docker_start_container - Start container
• docker_stop_container - Stop container gracefully
• docker_restart_container - Restart container
• docker_remove_container - Remove container
• docker_container_logs - Get container logs
• docker_exec_command - Execute command in container
• docker_container_stats - Get resource usage stats

Image Management (9 tools)

• docker_list_images - List images
• docker_inspect_image - Get image details
• docker_pull_image - Pull from registry
• docker_build_image - Build from Dockerfile
• docker_push_image - Push to registry
• docker_tag_image - Tag image
• docker_remove_image - Remove image
• docker_prune_images - Clean unused images
• docker_image_history - View layer history

Network Management (6 tools)

• docker_list_networks - List networks
• docker_inspect_network - Get network details
• docker_create_network - Create network
• docker_connect_container - Connect container to network
• docker_disconnect_container - Disconnect from network
• docker_remove_network - Remove network

Volume Management (5 tools)

• docker_list_volumes - List volumes
• docker_inspect_volume - Get volume details
• docker_create_volume - Create volume
• docker_remove_volume - Remove volume
• docker_prune_volumes - Clean unused volumes

System Tools (3 tools)

• docker_version - Get Docker version info
• docker_events - Get Docker events with optional time range and filters
• docker_prune_system - Clean all unused resources

Prompts

Five prompts help AI assistants work with Docker:

• troubleshoot_container - Diagnose container issues with logs and configuration analysis
• optimize_container - Get optimization suggestions for resource usage and security
• generate_compose - Generate docker-compose.yml from containers or descriptions
• debug_networking - Deep-dive analysis of container networking problems with systematic L3-L7 troubleshooting
• security_audit - Comprehensive security analysis following CIS Docker Benchmark with compliance mapping

Resource Templates

Two resource templates provide parameterized access to container data (discoverable via resources/templates/list):

• container://logs/{container_id} - Retrieve container logs (last 100 lines)
• container://stats/{container_id} - Get real-time resource usage statistics (CPU, memory, network, I/O)

Resource templates use URI parameters to dynamically generate resources. Clients can provide a container_id to access specific container data through the resources/read endpoint.

Safety System

The server implements a three-tier safety system with configurable operation modes and fine-grained tool filtering:

Operation Safety Levels

1. SAFE - Read-only operations (list, inspect, logs, stats)

   • Examples: docker_list_containers, docker_inspect_image, docker_container_logs

2. MODERATE - State-changing but reversible (start, stop, create)

   • Can modify system state
   • Controlled by SAFETY_ALLOW_MODERATE_OPERATIONS (default: true)
   • Examples: docker_create_container, docker_start_container, docker_pull_image

3. DESTRUCTIVE - Permanent changes (remove, prune)

   • Cannot be easily undone
   • Requires SAFETY_ALLOW_DESTRUCTIVE_OPERATIONS=true
   • Can require confirmation
   • Examples: docker_remove_container, docker_prune_images, docker_system_prune

Tool Filtering (Allow/Deny Lists)

In addition to safety levels, you can control exactly which tools are available using allow and deny lists:

Deny List - Block specific tools (takes precedence over allow list)

# Block destructive operations by tool name
SAFETY_DENIED_TOOLS="docker_remove_container,docker_prune_images,docker_system_prune"

Allow List - Only permit specific tools (empty = allow all based on safety level)

# Only allow read-only monitoring tools
SAFETY_ALLOWED_TOOLS="docker_list_containers,docker_inspect_container,docker_container_logs,docker_container_stats,docker_version"

How it works:

1. Safety level restrictions apply first (MODERATE/DESTRUCTIVE settings)
2. Deny list blocks specific tools regardless of safety level
3. Allow list (if non-empty) restricts to only listed tools
4. Tools are filtered in both list_tools() and at execution time

Use cases:

• Restrict AI agents to read-only operations for monitoring
• Block specific dangerous tools while allowing others at same safety level
• Create custom tool subsets for different user roles or environments
• Prevent accidental execution of critical operations

Safety Modes

Configure the safety mode using environment variables:

Read-Only Mode (Safest) - Monitoring and observability only

SAFETY_ALLOW_MODERATE_OPERATIONS=false
SAFETY_ALLOW_DESTRUCTIVE_OPERATIONS=false

# Optional: Explicitly allow only monitoring tools
SAFETY_ALLOWED_TOOLS="docker_list_containers,docker_list_images,docker_inspect_container,docker_inspect_image,docker_container_logs,docker_container_stats,docker_version,docker_system_info"

• ✅ List, inspect, logs, stats
• ❌ Create, start, stop, pull
• ❌ Remove, prune

Default Mode (Balanced) - Development and operations

SAFETY_ALLOW_MODERATE_OPERATIONS=true  # or omit (default)
SAFETY_ALLOW_DESTRUCTIVE_OPERATIONS=false

# Optional: Deny only the most dangerous operations
SAFETY_DENIED_TOOLS="docker_system_prune,docker_prune_volumes"

• ✅ List, inspect, logs, stats
• ✅ Create, start, stop, pull
• ❌ Remove, prune

Full Mode (Least Restrictive) - Infrastructure management

SAFETY_ALLOW_MODERATE_OPERATIONS=true
SAFETY_ALLOW_DESTRUCTIVE_OPERATIONS=true

• ✅ List, inspect, logs, stats
• ✅ Create, start, stop, pull
• ✅ Remove, prune

Note: Read-only mode is ideal for monitoring, auditing, and observability use cases where no changes to Docker state should be allowed.

MCP Server vs. Docker CLI

When to use MCP Server:

• Required: Claude Desktop (no other option)
• Recommended: Production automation, compliance requirements, multi-user access, safety controls needed

When to use CLI directly:

• Best for: Claude Code with simple tasks, advanced Docker features, minimal setup

Hybrid approach: Use MCP for common operations + CLI for advanced features.

Documentation

• - Security features, TLS/HTTPS, authentication, production checklist

Development

Setup Development Environment

# Clone repository
git clone https://github.com/williajm/mcp_docker.git
cd mcp_docker

# Install dependencies
uv sync --group dev

# Run tests
uv run pytest

# Run linting
uv run ruff check src tests
uv run ruff format src tests

# Run type checking
uv run mypy src tests

Running Tests

The project includes four levels of testing: unit, integration, end-to-end (E2E), and fuzz tests.

Test Level Comparison

Running Different Test Levels

# Run all tests with coverage
uv run pytest --cov=mcp_docker --cov-report=html

# Run unit tests only (fast, no Docker required)
uv run pytest tests/unit/ -v

# Run integration tests (requires Docker)
uv run pytest tests/integration/ -v -m integration

# Run E2E tests (requires Docker, comprehensive)
uv run pytest tests/e2e/ -v -m e2e

# Run E2E tests excluding stress tests
uv run pytest tests/e2e/ -v -m "e2e and not stress"

# Run fuzz tests locally (requires atheris)
python3 tests/fuzz/fuzz_validation.py -atheris_runs=10000

Fuzzing

The project uses ClusterFuzzLite for continuous fuzzing to meet OpenSSF Scorecard requirements. Fuzz tests run automatically in CI/CD to discover security vulnerabilities and edge cases.

Project Structure

mcp_docker/
├── src/
│   └── mcp_docker/
│       ├── __main__.py          # Entry point (transport selection)
│       ├── config.py            # Configuration management
│       ├── server/              # MCP server, prompts, resources
│       ├── tools/               # MCP tool implementations
│       ├── docker/              # Docker SDK wrapper
│       ├── services/            # Core services (audit, rate limiting, safety)
│       ├── middleware/          # Auth, safety, rate limiting middleware
│       └── utils/               # Validation, helpers, errors
├── tests/                       # Test suite
├── docs/                        # Documentation
└── pyproject.toml              # Project configuration

Requirements

• Python: 3.11 or higher
• Docker: Any recent version (tested with 20.10+)
• Dependencies:
  • mcp>=1.2.0 - MCP SDK
  • docker>=7.1.0 - Docker SDK for Python
  • pydantic>=2.0.0 - Data validation
  • loguru>=0.7.0 - Logging
  • secure>=1.0.1 - Security headers
  • authlib>=1.6.5 - OAuth/OIDC authentication (JWT validation)
  • httpx>=0.28.1 - HTTP client for OAuth token introspection
  • limits>=5.6.0 - Rate limiting
  • cachetools>=6.2.1 - JWKS caching

Code Standards

• Follow PEP 8 style guidelines
• Use type hints for all functions
• Write docstrings (Google style)
• Maintain high test coverage
• Pass all linting and type checking

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• Built with the Model Context Protocol by Anthropic
• Uses the official Docker SDK for Python
• Powered by modern Python tooling: uv, ruff, mypy, pytest