Docker Compose Orchestrator MCP: Manage Containers via Claude

By Deepak Bagada, CEO at SaaSNext & Principal AI Architect

DevOps and local development just got a massive AI upgrade. The Docker Compose Orchestrator MCP Server allows AI assistants in Cursor and Claude Desktop to natively interact with your Docker engine. Instead of manually running docker ps, writing complex awk scripts to parse logs, or digging through container states, your LLM can now inspect environments, analyze log streams for errors, and even deploy complex multi-container stacks autonomously.

Revolutionizing Local Development with AI

When an AI agent is helping you debug a full-stack application, it often lacks critical visibility into the runtime environment. If the frontend cannot connect to the backend API, the AI is essentially guessing. Is the backend container down? Did the database fail to initialize due to a bad volume mount? Is there a network bridge conflict?

With the Docker Compose Orchestrator MCP, the AI can independently verify the infrastructure. It can read the startup logs, inspect the container networking, and fix configuration errors in your docker-compose.yml file on the fly. This brings infrastructure-as-code and autonomous DevOps directly into your MCP ecosystem, saving countless hours of context switching and manual debugging.

Comprehensive Feature Set

This MCP server is built for robust, agentic workflows, providing a wide array of tools that map to standard Docker CLI commands but optimized for LLM consumption.

- **Container Lifecycle Management:** Start, stop, restart, pause, and inspect containers directly from the chat interface. The AI can manage the entire lifecycle autonomously.
- **Intelligent Log Analysis:** Stream and analyze container logs in real-time. The AI can grep for exceptions, stack traces, and out-of-memory (OOM) kills automatically without overwhelming its context window.
- **Compose Stack Deployment:** The agent can write a `docker-compose.yml` file, validate its syntax, and instantly bring up the stack (`docker-compose up -d`) to test its own code changes.
- **Network & Volume Introspection:** Debug complex microservice networking issues by inspecting Docker bridges, overlaid networks, and volume mounts to ensure data persistence and connectivity.
- **Resource Monitoring:** The AI can monitor CPU and memory usage (`docker stats`) to diagnose performance bottlenecks and memory leaks in real-time.

Real-World Agentic Workflows

Imagine an AI agent tasked with fixing a bug in a legacy Python application.

First, it uses the MCP server to spin up the required PostgreSQL database container. It then builds the Python Docker image, starts the container, and tails the logs. If the application crashes on startup due to a missing environment variable, the AI reads the traceback directly from the logs, patches the .env file, and restarts the container—all without human intervention. This is the power of agentic DevOps.

Configuration for Claude Desktop & Cursor

To enable the Docker Compose Orchestrator, you need to add it to your MCP client configuration. Ensure Docker Desktop (or the Docker daemon) is running and the Unix socket is accessible to the client process.

{
  "mcpServers": {
    "docker-orchestrator": {
      "command": "python",
      "args": ["-m", "docker_mcp_server"],
      "env": {
        "DOCKER_HOST": "unix:///var/run/docker.sock",
        "SAFE_MODE": "true",
        "MAX_LOG_LINES": "500"
      }
    }
  }
}

Input Schema (JSON/Zod) Definition

The server provides a robust set of well-typed tools. Here is the strict JSON schema for the get_container_logs tool, demonstrating how the AI queries logs for debugging while protecting its context window from massive log dumps:

{
  "name": "get_container_logs",
  "description": "Fetch logs from a specific Docker container. Use this to debug application crashes or startup failures.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "container_id": {
        "type": "string",
        "description": "The exact ID or name of the Docker container."
      },
      "tail": {
        "type": "number",
        "description": "Number of lines to show from the end of the logs. Keep under 500 to save context window.",
        "default": 100
      },
      "timestamps": {
        "type": "boolean",
        "description": "Include exact timestamps in the log output for chronologically debugging race conditions.",
        "default": false
      },
      "search_term": {
        "type": "string",
        "description": "Optional grep-style filter to only return lines containing this string (e.g., 'Exception' or 'Error')."
      }
    },
    "required": ["container_id"]
  }
}

OAuth 2.0 & Remote Security Architecture

While utilizing local Unix sockets is common for daily development, managing remote Docker Swarm, Kubernetes nodes, or Portainer instances requires strict enterprise security protocols. The Docker MCP Server supports OAuth 2.0 authentication when proxying traffic through a secure API gateway.

To secure remote Docker execution:

- Deploy an OAuth 2.0 proxy (such as OAuth2 Proxy or Pomerium) in front of your remote Docker API endpoint.
- Configure your enterprise Identity Provider (Okta, Auth0, Entra ID) to issue short-lived, scoped JWT tokens specifically for the MCP agent.
- Pass the token securely via the `DOCKER_BEARER_TOKEN` environment variable in your MCP configuration.
- Use Mutual TLS (mTLS) in conjunction with OAuth to ensure end-to-end encryption and strict client verification.

Security Warning: Never expose the raw Docker socket (TCP port 2375/2376) directly to the public internet, as it effectively provides root-level access to the host machine. Always integrate these tools into tightly secured, isolated workflows.

Python Implementation Blueprint

If you want to customize the server to include your company's specific deployment scripts, here is a foundational Python blueprint using the official Docker SDK for Python and the Model Context Protocol framework:

import docker
import os
from mcp.server import Server, StdioServerTransport
from mcp.types import Tool, TextContent, CallToolRequest

app = Server("docker-mcp-advanced")
client = docker.from_env()

# Safety flag to prevent catastrophic deletion
SAFE_MODE = os.getenv("SAFE_MODE", "true").lower() == "true"

@app.request_handler("ListToolsRequest")
async def list_tools():
    return {
        "tools": [
            Tool(
                name="list_containers",
                description="List all running and stopped Docker containers.",
                inputSchema={"type": "object", "properties": {}}
            ),
            Tool(
                name="get_container_logs",
                description="Retrieve logs for a specific container.",
                inputSchema={
                    "type": "object",
                    "properties": {
                        "container_id": {"type": "string"},
                        "tail": {"type": "number", "default": 100}
                    },
                    "required": ["container_id"]
                }
            )
        ]
    }

@app.request_handler("CallToolRequest")
async def call_tool(request: CallToolRequest):
    if request.params.name == "list_containers":
        containers = client.containers.list(all=True)
        result = [
            {"id": c.short_id, "name": c.name, "status": c.status, "image": c.image.tags[0] if c.image.tags else "none"}
            for c in containers
        ]
        return {"content": [TextContent(type="text", text=str(result))]}

    if request.params.name == "get_container_logs":
        container_id = request.params.arguments["container_id"]
        tail = request.params.arguments.get("tail", 100)
        try:
            container = client.containers.get(container_id)
            logs = container.logs(tail=tail).decode('utf-8')
            return {"content": [TextContent(type="text", text=logs)]}
        except docker.errors.NotFound:
            return {"content": [TextContent(type="text", text=f"Container {container_id} not found.")], "isError": True}

    raise Exception("Tool not found or not implemented")

async def main():
    transport = StdioServerTransport()
    await app.connect(transport)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

The Future of Agentic DevOps

The Docker Compose Orchestrator MCP transforms your AI from a mere code generator into a proactive, full-fledged Site Reliability Engineer (SRE). By allowing the AI to test, deploy, and debug in actual containers, you drastically reduce the feedback loop between writing code and shipping it to production. This is a critical, foundational building block for fully autonomous software development pipelines.

FAQs

Can the AI accidentally delete my production containers?

The MCP server includes a strict safety mode configuration. When SAFE_MODE=true is set in the environment variables (which is the default), destructive actions like docker rm, docker system prune, or docker volume prune are completely blocked.

Does this work with Podman or Colima?

Yes. Because Podman and Colima provide a Docker-compatible API socket, you can simply point the DOCKER_HOST environment variable to your alternative socket, and the MCP server will function normally without modifications.

Is this suitable for production Kubernetes environments?

While this tool is optimized for Docker Compose and Swarm, we recommend using a dedicated Kubernetes MCP server for K8s clusters. However, for remote Docker Swarm production deployments, this tool is highly effective provided the AI is restricted to read-only log inspection, tightly controlled by robust OAuth 2.0 and RBAC policies.