docker-mcp

AI-powered Docker management: an MCP server exposing 32 tools for natural-language container/image/volume/network operations, plus an A2A multi-agent layer where specialized agents autonomously diagnose and remediate container failures.

Why

Debugging a crashed container manually:

docker ps -a
docker inspect crashed-api
docker logs --tail 50 crashed-api
# ...squint at exit code 137, google what it means...

With docker-mcp you ask an LLM: "Why did my api container crash?" — it calls diagnose_container and answers: "exit 137 = SIGKILL, OOMKilled=true → the kernel killed it for exceeding its memory limit." Or ask "fix it" and auto_heal_container runs the multi-agent pipeline end to end.

Architecture

┌──────────┐    ┌─────────────────┐  JSON-RPC 2.0   ┌──────────────────────┐
│   LLM    │◄──►│   MCP client    │◄──(over stdio)─►│  docker-mcp server   │
│ (Claude) │    │ (Claude Desktop)│                 │  (32 MCP tools)      │
└──────────┘    └─────────────────┘                 └──────┬───────┬───────┘
                                                           │       │ auto_heal_container
                                               Docker SDK  │       │ (A2A JSON-RPC)
                                              (HTTP over   │   ┌───▼──────────────┐
                                               unix socket)│   │ diagnosis-agent  │
                                                    ┌──────▼┐  │        │artifact │
                                                    │dockerd│  │ remediation-agent│
                                                    └───────┘  └──────────────────┘

• Protocol layer — FastMCP handles the JSON-RPC handshake, advertises tool schemas (auto-derived from type hints + docstrings), dispatches tools/call requests.

• Tool layer — five domain modules (containers 11, images 5, volumes 5, networks 7, diagnostics 3) + the A2A bridge (1). Adding a domain = one module

  • one register() call.

• Docker layer — one lazy singleton SDK client (client.py); every SDK exception becomes a structured {"error", "error_type"} result so the LLM can self-correct.

• A2A layer — DiagnosisAgent (read-only evidence gathering + root-cause classification) and RemediationAgent (declarative policy table, allowlisted non-destructive actions, dry-run by default), chained by a transport-independent Orchestrator that discovers agents via their Agent Cards. See docs/A2A.md.

Quickstart

Prerequisites: Python 3.10+, Docker running.

pip install -e .

Claude Desktop config (claude_desktop_config.json):

{"mcpServers": {"docker": {"command": "docker-mcp"}}}

Run the A2A agents as real HTTP services (optional — the MCP bridge runs them in-process by default):

python -m docker_mcp.a2a.serve diagnosis   --port 9001
python -m docker_mcp.a2a.serve remediation --port 9002

Tests (mocked daemon, no Docker needed):

python -m pytest tests/ -v   # 13 tests

Tools at a glance