Docker MCP Server

Exposes 20+ discrete Docker operations (container lifecycle, image management, network/volume operations) as MCP tools with strict input validation via Pydantic schemas and serialized outputs through output_schemas.py. Each tool is registered via @app.call_tool() decorators that handle MCP protocol requests over stdio, validate inputs against input_schemas.py models, execute Docker SDK calls, and serialize results back to the client. This architecture decouples LLM clients from direct Docker SDK knowledge while enforcing type safety at the protocol boundary.

Implements a two-phase interaction model where the LLM first queries current Docker state (list_containers, list_images, etc.), generates a natural language plan describing desired changes, presents it 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 → user approval → execution, reducing the risk of unintended infrastructure mutations. The workflow leverages tool composition — the prompt orchestrates multiple tool calls in sequence to gather context before proposing 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.

Provides granular control over individual container lifecycle through tools like run_container, stop_container, restart_container, and remove_container. The run_container tool accepts structured inputs for image selection, environment variables, port mappings, volume mounts, and resource limits, then executes via the Docker Python SDK's container.run() method. Each operation is validated against Pydantic schemas (e.g., RunContainerInput) and returns structured metadata (container ID, status, ports). This enables fine-grained container orchestration without requiring users to construct Docker CLI commands.

Provides tools for image lifecycle management including pull_image (fetch from registries), build_image (build from Dockerfile with build context), list_images (enumerate local images with metadata), and remove_image (delete unused images). The build_image tool accepts a Dockerfile path and build context directory, then executes docker.images.build() with streaming output. The pull_image tool supports registry authentication via Docker credentials. All operations return structured metadata (image ID, tags, size, creation date) and are validated against Pydantic schemas. This enables LLMs to manage the full image lifecycle without direct Docker CLI access.

Provides tools for managing Docker networks (create_network, list_networks, remove_network, inspect_network) and volumes (create_volume, list_volumes, remove_volume, inspect_volume). These tools allow LLMs to create custom bridge networks for container communication, define named volumes for persistent storage, and inspect infrastructure metadata. Network creation accepts driver type (bridge, overlay) and IPAM configuration; volume creation accepts driver and mount options. All operations return structured metadata (network ID, subnet, connected containers; volume ID, mount point, driver) and are validated against Pydantic schemas.

Implements MCP resources (read_resource handler) that stream container logs and performance statistics in real-time. The server exposes resources like 'docker://logs/{container_id}' and 'docker://stats/{container_id}' that clients can subscribe to for continuous log output and CPU/memory/network metrics. This leverages the Docker SDK's logs() and stats() methods with streaming enabled, serializing output through output_schemas.py. Unlike tools (which are request-response), resources maintain open connections for continuous data flow, enabling LLMs and clients to monitor container health without polling.

Provides the exec_container tool that executes arbitrary commands inside a running container and captures output. The tool accepts a container ID/name, command string, and optional stdin input, then uses the Docker SDK's exec_run() method to execute the command with output streams captured. Results are serialized as structured JSON containing exit code, stdout, and stderr. This enables LLMs to run diagnostic commands (e.g., 'ps aux', 'curl localhost:8080') or administrative tasks inside containers without direct shell access.

Supports both local Docker daemon connections (via Unix socket at /var/run/docker.sock) and remote connections (via SSH using DOCKER_HOST environment variable). The server uses the Docker Python SDK's from_env() method to read standard Docker environment variables (DOCKER_HOST, DOCKER_CERT_PATH, etc.) during initialization. For remote connections, DOCKER_HOST can be set to 'ssh://user@host' and the server will tunnel Docker API calls over SSH. This is configured via ServerSettings which reads environment variables, enabling deployment flexibility without code changes.

All MCP tool inputs are validated using Pydantic models defined in input_schemas.py (e.g., RunContainerInput, PullImageInput) before execution, and outputs are serialized using functions from output_schemas.py. This creates a strict type boundary at the MCP protocol level — invalid inputs are rejected with validation errors before reaching Docker SDK code, and outputs are guaranteed to conform to expected schemas. The validation includes type checking, required field enforcement, and custom validators for Docker-specific constraints (e.g., valid image names, port ranges).

The server uses MCP framework decorators (@app.list_tools(), @app.call_tool(), @app.get_prompt(), @app.read_resource()) to register handlers for different MCP interaction types. Each decorator maps to a handler function that receives MCP protocol requests, validates inputs using Pydantic, executes Docker operations, and returns serialized results. This decorator-based registration pattern decouples handler logic from protocol plumbing — developers add new tools by defining a handler function and decorating it, without manually managing request routing or serialization.