Docker MCP Server

Exposes 20+ discrete Docker operations (container lifecycle, image management, network/volume operations) as MCP tools with standardized request/response handling. Each tool is registered via @app.call_tool() decorator, validates inputs using Pydantic schemas from input_schemas.py, executes operations through the Docker Python SDK (v7.1.0+), and serializes responses using output_schemas.py. Supports both local Unix socket and remote SSH connections via DOCKER_HOST environment variable.

Implements a two-phase infrastructure change pattern where the LLM first queries current Docker state using tools like list_containers(), generates a human-readable plan describing desired changes, presents the plan to the user for review, and only executes approved operations. This is registered as an MCP prompt (docker_compose) that guides the LLM through state inspection, planning, and conditional execution. The workflow prevents accidental destructive operations by requiring explicit user approval before applying changes.

The server is a Python 3.12+ application that communicates with MCP clients over stdin/stdout using JSON-RPC protocol. The server runs as a long-lived process that reads MCP requests from stdin, processes them (validating inputs, executing Docker operations, serializing outputs), and writes responses to stdout. This stdio-based communication model enables the server to be launched by MCP clients (e.g., Claude Desktop) without requiring separate network infrastructure — the client spawns the server as a subprocess and pipes requests/responses through standard streams.

The server uses the Docker Python SDK (7.1.0+) to abstract Docker daemon API interactions. Rather than constructing raw HTTP requests to the Docker daemon, the server calls SDK methods like docker.containers.run(), docker.images.pull(), docker.networks.create(), etc. The SDK handles connection pooling, request serialization, response parsing, and error handling. This abstraction layer insulates the MCP server from Docker API versioning and protocol details, allowing it to work with different Docker daemon versions without code changes.

Exposes container logs and performance metrics (CPU, memory, network I/O) as MCP resources that stream data in real-time. Implemented via @app.read_resource() handlers that connect to the Docker daemon's log and stats APIs, format output as text or structured data, and push updates to the MCP client. Resources are identified by container ID and can be subscribed to for continuous monitoring without polling.

Provides granular control over container lifecycle through discrete MCP tools (run_container, start_container, stop_container, restart_container, remove_container). Each operation accepts configuration parameters (image, ports, environment variables, volumes, resource limits) as Pydantic-validated inputs, executes through the Docker Python SDK, and returns container ID or status. Supports both simple operations (stop a running container) and complex configurations (run with custom networks, mounts, and resource constraints).

Exposes Docker image operations as MCP tools: pull_image (fetch from registry), build_image (build from Dockerfile), list_images (enumerate local images), inspect_image (get metadata), remove_image (delete). Each tool validates inputs via Pydantic, executes through Docker SDK, and returns structured metadata (image ID, tags, size, creation date). Build operations accept Dockerfile content or path and build context; pull operations support authentication via registry credentials.

Provides MCP tools for Docker network and volume operations: create_network (define custom networks), list_networks/list_volumes (enumerate infrastructure), inspect_network/inspect_volume (get metadata), remove_network/remove_volume (delete), connect_container_to_network (attach running containers). Each operation validates inputs via Pydantic, executes through Docker SDK, and returns structured metadata. Supports network drivers (bridge, overlay, host) and volume drivers (local, named).

Supports connecting to Docker daemons running on remote machines via SSH by reading the DOCKER_HOST environment variable. The server uses the Docker Python SDK's from_env() method, which automatically parses DOCKER_HOST (e.g., 'ssh://user@host:22/run/docker.sock') and establishes SSH tunnels. This enables managing production Docker engines on remote servers without exposing the daemon socket directly or requiring VPN access.

Provides an MCP tool (exec_container) that executes arbitrary commands inside running containers and captures stdout/stderr output. Implemented via Docker SDK's exec_run() method, which creates an exec instance, runs the command, and streams output back to the MCP client. Supports both interactive (TTY) and non-interactive execution modes, environment variable injection, and working directory specification.

All MCP tools use Pydantic models (defined in input_schemas.py) to validate incoming requests before execution. Each tool's parameters are documented as a Pydantic schema that Claude can introspect, providing type hints, required/optional fields, and validation rules. Invalid inputs are rejected with detailed error messages before reaching the Docker SDK, preventing malformed requests from causing daemon errors. Output schemas (output_schemas.py) similarly document response formats.

Implements the MCP server as a long-lived Python process that communicates with clients (Claude Desktop) over stdio using the MCP protocol. The server registers handlers via decorators (@app.list_tools(), @app.call_tool(), @app.get_prompt(), @app.read_resource()) and responds to incoming requests without maintaining session state. Configuration is read from environment variables (DOCKER_HOST, etc.) at startup. The server runs continuously, handling multiple requests from the same client without restart.