docker-mcp

Enables Claude AI to create and instantiate Docker containers from images through conversational requests by translating natural language intent into structured container creation parameters (image, name, ports, environment variables). The MCP server receives the user's natural language request, Claude interprets it and invokes the create-container tool with appropriate parameters, which the Docker Handlers layer processes and passes to the Docker Executor for platform-specific command execution via the python-on-whales library.

Allows Claude to deploy multi-container applications by accepting a Docker Compose YAML configuration and orchestrating the full stack deployment through the MCP protocol. The deploy-compose tool receives a project name and compose YAML content, the Docker Handlers validate and process the configuration, and the Docker Executor invokes docker-compose commands via python-on-whales to bring up all defined services, networks, and volumes in a single coordinated operation.

Enables Claude to fetch and analyze container logs by accepting a container name and retrieving the full log stream from the Docker Engine via python-on-whales. The get-logs tool queries the Docker daemon for container logs, streams or buffers the output, and returns the log content to Claude for analysis, summarization, or troubleshooting without requiring users to run docker logs commands manually.

Provides Claude with a real-time view of all Docker containers and their status by exposing a list-containers tool that queries the Docker daemon and returns container metadata (name, ID, status, image, ports). The Docker Handlers layer processes the query, the Docker Executor invokes docker ps via python-on-whales, and the results are formatted and returned to Claude for status monitoring, resource planning, or operational awareness without requiring CLI invocation.

Implements a full Model Context Protocol (MCP) server that establishes bidirectional communication with Claude Desktop, exposing Docker tools as callable functions through the MCP specification. The server component (src/docker_mcp/server.py) handles MCP message parsing, tool registration, request routing, and response serialization, allowing Claude to discover available Docker tools and invoke them with structured parameters through the MCP transport layer.

Abstracts platform-specific Docker command execution differences (Windows vs Unix/Linux) through the python-on-whales library, allowing the same Docker operations to work seamlessly across operating systems. The Docker Executor layer translates high-level Docker operations into platform-appropriate commands, handling differences in Docker socket paths, command syntax, and process management without exposing platform-specific logic to the MCP server or handlers.

Implements a tool registry and parameter validation system where each Docker operation (create-container, deploy-compose, get-logs, list-containers) is defined with explicit parameter schemas, allowing the MCP server to validate incoming requests before passing them to Docker Handlers. The server component maintains a registry of available tools with their parameter specifications, validates Claude's tool invocation requests against these schemas, and routes validated requests to the appropriate handler function.

Provides an intermediate processing layer between the MCP server and Docker Executor that handles Docker-specific business logic, request transformation, and error handling. The Docker Handlers component (referenced in architecture docs) receives validated tool invocation requests from the MCP server, applies Docker-specific logic (e.g., image availability checks, compose file parsing), transforms parameters into executor-compatible formats, and coordinates with the Docker Executor for actual command execution.