docker-mcp-server

More than just a fully featured MCP server that lets AI agents manage Docker - containers, images, networks, volumes, swarm services, secrets, configs, nodes, plugins, etc., it helps you create workflows to easily manage your Docker environments.

It gives you much more control and flexibility than calling the Docker CLI directly: each operation is exposed as its own typed tool, marked read-only or not, with destructive actions separately flagged. This means a client can auto-approve reads while always confirming anything destructive, and the whole server can also be switched into a read-only or no-destructive mode as a blanket safeguard. Output is bounded rather than left to grow unboundedly - capped with a truncated flag instead of silently overflowing the agent's context.

For simple cases, you can just install and go with no configuration required - once loaded it will discover your local Docker socket and expose the full command surface to your AI agent. For more advanced users it can manage multiple Docker daemons, e.g. both your local dev environment and also a remote production environment over TCP, TLS or SSH in a single session. It can also be configured to mark some daemons as read-only, so you can monitor them without the risk of making accidental changes.

It can even be run on a machine without Docker installed and manage remote daemons over SSH, TLS or TCP (some features require SSH). The AI itself does not require shell or SSH access.

The MCP server also exposes things like logs and stats as resources so that you can monitor and triage, enabling you to answer questions like 'why did my container crash?', 'what is the state of my swarm?', 'am I suffering memory pressure?', 'what is the disk usage of my volumes?', 'what differences are there between my test and production systems?', and more...

Documentation is built for the agent, not just the person configuring it: an MCP resource exposes the Docker SDK reference in-session (with a tool-callable fallback for clients that can't read resources), and a live tool-catalog resource reports exactly what's registered under the current configuration. Each tool's own description names its nearest siblings and when to prefer each, states preconditions and side effects in plain language, and is honest about when it can still fail - so an agent can pick the right tool on the first try among 150+ options, not guess.

docker-mcp-server is optimized to work efficiently with the new generation of MCP clients that support lazy tool loading. For clients that still eagerly load all tools, the server can optionally be configured to exclude tools from a subset of domains (e.g. exclude 'swarm' and 'scout' tools) to reduce the tool list size. It's also possible to put the MCP server into 'read-only' or 'no-destructive' modes that prevent any tools with write or destructive capabilities from being registered, which again reduces the footprint.

The server runs entirely on your machine, either natively, as an mcpb bundle, or containerized, and sends no telemetry. You are entirely in control - see the Privacy Policy.

Requirements

Note: If you're using the containerized MCP server or MCPB bundle, the Python and uv requirements are taken care of for you.

• A running Docker daemon reachable from the host that runs the server (the standard DOCKER_HOST / unix socket conventions apply)
• Python ≥ 3.14
• uv for dependency management
• Intel (x86_64) macOS only: installing natively (via uvx/pip, or the .mcpb bundle, both of which resolve dependencies locally) requires Rust and OpenSSL 3.x, because cryptography - a transitive dependency, via mcp -> pyjwt[crypto] - has shipped no x86_64 macOS wheel since version 49.0.0 and must be built from source there. If you'd rather not install a build toolchain, use the container image instead - it runs the same prebuilt Linux binary regardless of your Mac's CPU architecture, so this doesn't apply to it. See Security considerations for more.

Using the server

The server is published to PyPI as docker-mcp-server. Add an entry to your AI tool's MCP configuration (commonly mcp.json or the equivalent in your client) pointing uvx at it - uv will fetch and cache the package on first use:

{
  "mcpServers": {
    "docker-mcp-server": {
      "command": "uvx",
      "args": ["docker-mcp-server"],
      "env": {}
    }
  }
}

To pin a specific version, append ==<version> to the package name (e.g. docker-mcp-server==1.5.0). If you'd rather install it onto your PATH, pipx install docker-mcp-server gives you the docker-mcp-server console script (a docker-mcp alias is also installed).

Installing from git instead. To run an unreleased revision straight from this repository:

{
  "mcpServers": {
    "docker-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/L337-org/docker-mcp.git",
        "docker-mcp-server"
      ],
      "env": {}
    }
  }
}

To pin a specific revision, append @<tag-or-commit> to the git URL.

Install as a Desktop Extension (.mcpb)

For Claude Desktop, a one-click bundle is attached to each GitHub Release as docker-mcp-server-<version>.mcpb (with a matching .sha256). Download it and drag it into Settings > Extensions, or use Settings > Extensions > Advanced settings > Install extension... and pick the file. The install dialog surfaces a Docker host(s) field and the read-only / no-destructive / disabled-domain switches, so no manual JSON editing is needed.

It's a uv-type bundle: Claude Desktop's managed uv resolves the dependencies and runs the server, so the only host prerequisite is Docker itself - no separate Python, uv, or git. Leave the Docker host(s) field blank to use your default Docker context; set one endpoint (ssh://user@host) for a remote daemon, or list several (see Managing several daemons).

Run as a container

Running the server as a container removes the Python / uv / git prerequisites entirely - the only thing the host needs is Docker, which you already have. Prebuilt multi-arch images (linux/amd64 + linux/arm64) are published on each release to Docker Hub (gavinlucas/docker-mcp-server) and GHCR (ghcr.io/l337-org/docker-mcp-server) - the two are identical. Point your MCP client at docker run:

{
  "mcpServers": {
    "docker-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "gavinlucas/docker-mcp-server:latest"
      ],
      "env": {}
    }
  }
}

-i is required (the server speaks MCP over stdio); --rm cleans up when the client disconnects. To pin a version, replace :latest with a release tag (e.g. :1.5.1). To pull from GHCR instead, use ghcr.io/l337-org/docker-mcp-server:latest.

Image renamed. As of 1.5.0 the image is published as docker-mcp-server (matching the PyPI name). The old ghcr.io/gavinlucas/docker-mcp image is frozen at 1.4.0 and no longer updated - point new pulls at ghcr.io/l337-org/docker-mcp-server.

Image variants. Two variants are published to both registries (gavinlucas/docker-mcp-server on Docker Hub and ghcr.io/l337-org/docker-mcp-server on GHCR), both built from one Dockerfile. The CLI-backed domains (Compose, Stack, Buildx, Scout, Context) shell out to the docker CLI and its plugins.

Scout's plugin binary alone accounts for the ~195 MB jump from no-scout to full. The no-scout image also defaults DOCKER_MCP_SERVER_DISABLE=scout, so the scout tools don't register - the agent is never offered tools whose CLI plugin isn't present (it sees a smaller, fully-working tool list rather than scout tools that error on every call). Override at runtime with -e DOCKER_MCP_SERVER_DISABLE=... if you ever need to change the disabled set (note it replaces, not appends).

Building it yourself. All variants build from the repo's Dockerfile via build args:

docker build -t docker-mcp-server:full .                                    # full (default)
docker build --build-arg INSTALL_SCOUT=0 --build-arg DISABLE_DOMAINS=scout \
  -t docker-mcp-server:no-scout .                                           # no-scout
docker build --build-arg INSTALL_CLI=0 -t docker-mcp-server:lite .          # lite (SDK-only, ~165 MB)

The lite image (docker-py SDK tools only - Compose/Buildx/Scout/Context degrade to "plugin unavailable") is buildable but not published.