Docker MCP Server (docker-mcp)

Model Context Protocol (MCP) server providing high-leverage tools for inspecting, orchestrating, and troubleshooting Docker Engine and Docker Compose environments.

Built on @thargy/mcp-server-core following John Ousterhout’s Deep Module philosophy (A Philosophy of Software Design).

---

1. Architectural Vision: Deep Module vs. Tool Bloat

Traditional MCP servers map 1:1 to Docker CLI verbs, resulting in 25+ shallow tools that bloat LLM context windows (consuming 4,000+ prompt tokens per turn) and increase hallucinations.

docker-mcp exposes exactly 6 consolidated, high-leverage tools with polymorphic typed action discriminators, consuming <1,000 tokens:

graph LR
    subgraph Clients ["MCP Clients"]
        Claude["Claude Desktop (Stdio)"]
        Agent["Antigravity / Coding Agents"]
        Gateway["mcp-gateway (SSE / Streamable HTTP)"]
    end

    subgraph DeepModule ["docker-mcp (Deep Module)"]
        T1["docker_containers"]
        T2["docker_compose"]
        T3["docker_images"]
        T4["docker_volumes"]
        T5["docker_networks"]
        T6["docker_system"]
        
        Seam["IDockerClient Seam"]
        Engine["DockerodeClient / InMemoryDockerClient"]
    end

    subgraph Host ["Docker Infrastructure"]
        Socket["/var/run/docker.sock"]
        RemoteTCP["tcp://remote-host:2376"]
        RemoteSSH["ssh://user@remote-host"]
    end

    Clients --> DeepModule
    DeepModule --> Seam
    Seam --> Engine
    Engine --> Host

---

2. Consolidated MCP Tool Catalog

Tool	Actions	Capabilities & Highlights
docker_containers	list, inspect, start, stop, restart, logs, stats, exec, remove	Name/status regex filtering, real-time CPU/RAM calculation, multiplexed stdout/stderr log extraction, command execution, safe timeouts.
docker_compose	ps, up, down, restart, logs	Multi-container stack discovery via labels/directories, lifecycle orchestration, healthcheck readiness verification.
docker_images	list, inspect, pull, prune, remove	Image inventory, virtual size formatting, tag resolution, dangling image cleanup.
docker_volumes	list, inspect, create, prune, remove	Persistent volume catalog, driver inspection, orphan volume pruning.
docker_networks	list, inspect, create, prune, remove	Bridge, overlay, and macvlan network topology inspection and subnet resolution.
docker_system	info, df, prune, version, ping	Daemon healthcheck, engine version, disk usage breakdown, system-wide reclamation.

---

3. Quickstart & Configuration

Environment Variables

Variable	Default	Description
PORT	3008	HTTP / SSE listen port
HOST	0.0.0.0	Bind address
MCP_TOKEN	optional	Secret token for Bearer authentication over HTTP / SSE
DOCKER_SOCKET	/var/run/docker.sock	Path to local Unix Docker socket
DOCKER_HOST	optional	Remote Docker TCP URL (e.g. tcp://192.168.86.50:2376)
DOCKER_TLS_VERIFY	optional	Enable TLS certificate verification (1 or 0)
DOCKER_CERT_PATH	optional	Path to client TLS certificates (ca.pem, cert.pem, key.pem)

Running with Stdio (Claude Desktop / Local CLI)

{
  "mcpServers": {
    "docker": {
      "command": "node",
      "args": ["/Users/craigdean/Repos/docker-mcp/dist/src/index.js"],
      "env": {
        "DOCKER_SOCKET": "/var/run/docker.sock"
      }
    }
  }
}

Running with Docker Compose & mcp-gateway

docker compose up -d --build

Access HTTP SSE at http://localhost:3008/docker/mcp or http://localhost:3008/docker/sse.

---

4. Testing & Code Quality

100% of unit tests execute against InMemoryDockerClient without requiring access to a live Docker socket.

# Run unit tests
npm test

# Run test coverage (>85% required)
npm run test:coverage

# TypeScript compile check
npm run types:check

---

License

MIT © 2026 Craig Dean