Docker MCP Server

Update swarm-wide settings: the single home for join-token rotation and cluster spec changes. Must be called on a swarm manager node. Token rotation invalidates the old join token immediately - nodes that have not yet joined using the old token must use the new one. Existing joined nodes are unaffected. Use `swarm_join_tokens` to retrieve the new tokens after rotation. Rotating the unlock key requires all managers to be re-unlocked on restart with the new key; retrieve it immediately via `swarm_unlock_key`. Rotation and `updates` are independent and may be combined in one call; `swarm_init` sets these same fields when the swarm is first created, and `swarm_inspect` reads the current values back. The Engine replaces the whole cluster spec on every update, so this reads the current spec first and resubmits it, merging `updates` over it - omitting `updates` therefore changes nothing but the requested rotation. Args: rotate_worker_token: Issue a new worker join token, invalidating the current one rotate_manager_token: Issue a new manager join token, invalidating the current one rotate_manager_unlock_key: Issue a new autolock unlock key for manager restart updates: Engine SwarmSpec fields to change, merged over the current spec one top-level key at a time, so a named block is replaced whole rather than field by field: keys are "Name", "Labels", "Orchestration", "Raft", "Dispatcher", "CAConfig", "EncryptionConfig" and "TaskDefaults", e.g. {"EncryptionConfig": {"AutoLockManagers": True}} to turn manager autolock on. Read the current blocks from `swarm_inspect` Returns: bool: True after the update completes

Close and drop pooled Docker client connection(s); each is rebuilt lazily on next use. Use this to force a stale or errored connection to be discarded. Prefer `system_reconnect` when you want to immediately re-establish the connection rather than wait for the next tool call to trigger a lazy rebuild. With `host` omitted every pooled client is closed (unlike other tools, where omitting it means the default host). Closing clients does not affect running containers. Returns: bool: True once closed

Summarize Docker disk usage: layer storage plus per-object sizes for images, containers, volumes, build cache. Equivalent to `docker system df`. Use it to find what to reclaim before `image_prune` / `container_prune` / `volume_prune` / `buildx_prune`; use `system_info` for daemon config and counts rather than sizes. The reply enumerates every object on the daemon, so expect a large payload on busy hosts. Returns: dict: {"LayersSize", "Images", "Containers", "Volumes", "BuildCache"} with per-object size fields

Stream real-time events from the Docker server, bounded by `limit` events or `timeout_seconds`. Returns when `limit` events are collected or `timeout_seconds` elapses, whichever comes first (`limit` caps memory; `timeout_seconds` caps how long the call blocks - without it a quiet daemon would block indefinitely, since the stream only yields on an actual event). Caveat for `ssh://` daemons: docker-py can't cancel an SSH stream, so the `timeout_seconds` watchdog can't interrupt a fully idle stream - bound with `until`/`limit` (or a non-SSH endpoint). "Wait for the next matching event" idiom: pass `limit=1` with `filters` narrowed to what you care about (e.g. `{"type": "container", "event": "health_status"}`) and a generous `timeout_seconds`. This blocks until that one event arrives (or the timeout elapses, returning an empty list) instead of re-polling a snapshot on a timer - there's no separate wait tool for this since the filtering this call already does covers it. Args: since: Show events created since this timestamp until: Show events created until this timestamp filters: Filters to apply to the event stream limit: Max events to return timeout_seconds: Max wall-clock seconds before returning what was collected Returns: list: A list of decoded event dicts (length <= limit)

Return system-wide Docker information, like `docker info`. Daemon runtime state: container/image counts, storage and logging drivers, swarm role, and daemon warnings. Use `system_version` for version/API level and `system_df` for disk usage. Returns: dict: {"Containers", "Images", "Driver", "ServerVersion", "Swarm", "Warnings", ...}

Authenticate with a Docker registry. Security: the password is sent as a tool argument, which many MCP clients log verbatim. Prefer running `docker login` once on the host so the `docker` module reuses the credentials cached in `~/.docker/config.json`, and avoid calling this tool from an agent loop. Credentials let `image_pull` / `image_push` reach private repositories; `system_logout` clears them. Args: username: Registry username password: Registry password or token email: Registry account email registry: URL to the registry (defaults to Docker Hub) reauth: Force re-authentication even if valid credentials exist dockercfg_path: Path to a custom dockercfg file Returns: dict: The login response: {"Status"} always; "IdentityToken" only when the registry issues one

Clear cached registry credentials from this server's in-memory Docker client. docker-py / the Engine have no true logout: `system_login` validates against the registry (the daemon's `/auth` is stateless) and caches credentials in-process. This drops that in-memory cache; it does NOT contact the daemon or touch the host's `~/.docker/config.json`. With no `registry`, clears every cached credential; pass one to clear just that entry (key must match `system_login`; Docker Hub is cached under "docker.io"). `system_close`/`system_reconnect` also clear it by discarding the client. Reaches into a private docker-py attribute (`api._auth_configs`); degrades to clearing nothing if that internal shape changes. Args: registry: Registry key to clear, or None to clear every cached credential Returns: dict: {"cleared": [<registry keys removed>]}

Check that the Docker server is responsive. The cheapest daemon health check. A failure here usually means connection config rather than daemon load - `system_reconnect` rebuilds a wedged client, `host_list` shows the configured endpoints. For daemon details use `system_version` / `system_info`. Returns: bool: True if the daemon responded successfully

Rebuild a pooled Docker client from its configured endpoint, to recover a wedged connection. Validates the rebuilt client before swapping in (and only then closes the old one), so a failed rebuild leaves the working client in place. Rebuilds the default host's client when `host` is omitted. It CANNOT retarget to a different daemon - to add or change a daemon, edit DOCKER_MCP_SERVER_HOSTS and restart. `system_close` closes pooled clients without rebuilding; `host_list` shows the configured endpoints. Returns: dict: the rebuilt host's version info (same shape as `system_version`), confirming connectivity

Return Docker server version information. Engine version, API level, and per-component versions - the first thing to check for feature availability. `system_info` reports runtime state (counts, drivers, swarm role) instead. Returns: dict: {"Version", "ApiVersion", "MinAPIVersion", "Os", "Arch", "Components", ...}

List this server's registered tools as compact rows, filtered by domain, category or keyword. A tool-callable mirror of `docker-mcp://tool-catalog` for clients that can't read MCP resources (e.g. Claude Desktop, Cursor), and the only way to ask what no per-tool description search can express: which tools are destructive, which accept a `host`, what this server actually registered. Use it to brief on an unfamiliar area (`domain="buildx"` returns one line per tool rather than ~13 full definitions), to check blast radius (`category="destructive"`), or to establish that nothing matches - `matched: 0` is a definitive negative, which a client's fuzzy search cannot give. Covers this server's own surface; `docs_lookup` covers external Docker reference documentation. Rows are summaries, not definitions - fetch a tool's own definition for its parameters. Read-only, never raises on a query matching nothing, and always registered even when DOCKER_MCP_SERVER_DISABLE drops every domain. A tool dropped by a switch or a disabled domain is absent rather than flagged; `hidden_by_configuration` reports how many each domain hides. Args: domain: Exact domain name (see any result's `domains` key); omit for every domain category: Exact category; omit for all three keyword: Case-insensitive substring over tool names, summaries and parameter names Returns: dict: {"matched": int, "tools": [{"name", "domain", "category", "summary"}], "domains": {domain: count}, "no_domain": int, "hidden_by_configuration": {domain: count}, "switches", "filters"}. Every `domains` key is a value `domain` accepts; `no_domain` counts the domain-less tools, whose rows carry `domain: null` and which no `domain` value selects.

Create a volume managed by Docker. Named volumes persist after their containers stop or are removed; use them for databases, uploads, or any data that must outlive a container. Anonymous volumes (no `name`) are only removed automatically when the container was started with `--rm` or removed with `docker rm -v`; otherwise they accumulate and must be pruned manually. Common `driver_opts` for the default `local` driver: bind-mount an existing host path with `{"type": "none", "device": "/host/path", "o": "bind"}`, or mount an NFS share with `{"type": "nfs", "device": "server:/export", "o": "addr=server,rw"}`. Third-party drivers (e.g. `rexray`, `convoy`) accept their own option keys. List existing volumes with `volume_list`; reclaim unused ones with `volume_prune`. Created volumes are stamped with provenance labels. Args: name: Volume name; auto-generated if omitted (creates an anonymous volume) driver: Volume driver to use (default: "local") driver_opts: Driver-specific options dict labels: Labels to set on the volume Returns: dict: The created volume's full document (keys include Name, Driver, Mountpoint, CreatedAt, Labels, Options, Scope)

Get a volume's full inspect payload by name. Use it after `volume_list` to see a volume's on-disk location, driver, and labels - e.g. before a backup or `volume_remove`. Volumes are addressed purely by name; they have no separate id. Args: name: The volume name (volumes have no ids) Returns: dict: The volume's full document (keys include Name, Driver, Mountpoint, CreatedAt, Labels, Options, Scope)

List volumes. Volumes are addressed by name only - feed a Name to `volume_inspect` for detail or `volume_remove` / `volume_prune` to clean up. filters={"dangling": True} finds volumes that no container references. Args: filters: Filter by attributes (e.g. dangling, name, label) managed_only: Only return volumes created by this MCP server (filters on the docker-mcp-server.managed label); combines with any `filters` given Returns: list: One volume document ({"Name", "Driver", "Mountpoint", ...}) per volume

Remove volumes not referenced by any container, running or stopped. A volume used by even one stopped container is not "unused" and survives the prune - remove the container first (or use `container_prune`, then this) to reclaim its volumes. Valid filter keys: `label` (key or key=value), `all` ("true" as a string - without it only anonymous volumes are eligible, matching `docker volume prune`'s default). Use `volume_list` first to see what currently exists. Args: filters: Narrow which unused volumes to remove; omit to remove all anonymous ones Returns: dict: {"VolumesDeleted": [...], "SpaceReclaimed": <bytes>}

Remove a single volume by name. Fails if any container, running or stopped, still references the volume - remove or recreate those containers first, or pass `force=True` to remove it anyway (the containers keep their reference but lose the underlying data). For bulk cleanup of volumes with no container references at all, use `volume_prune` instead. Args: name: Volume name to remove force: Remove even if a container still references the volume Returns: bool: True after removal