Docker MCP Server

Activate an installed plugin so Docker routes relevant API calls through it. Activates a plugin that is currently disabled — either freshly installed or previously disabled via `plugin_disable`. If the plugin exposes configuration (check via `plugin_inspect`), call `plugin_configure` while it is still disabled before enabling it. `timeout_seconds` controls how long Docker waits for the plugin process to become healthy; 0 means wait indefinitely. args: name - The plugin name to enable timeout_seconds - Seconds to wait for the plugin to become healthy (0 = no timeout) returns: bool - True after the plugin is enabled

Return the full attrs for a single installed plugin. Use this to check a plugin's `Enabled` state before calling `plugin_enable` / `plugin_disable`, or to read the config keys it exposes under `Settings.Env` before calling `plugin_configure`. For the set of all installed plugins use `plugin_list`. args: name - Plugin name, e.g. "vieux/sshfs:latest" returns: dict - The plugin's attrs, including `Enabled` and `Settings`

Install a plugin from Docker Hub. `remote` is a Docker Hub reference in `author/name:tag` form, e.g. `vieux/sshfs:latest`. The daemon handles permission grants non-interactively. After installation use `plugin_inspect` to confirm the plugin's enabled state, then call `plugin_enable` to activate it if needed, and optionally `plugin_configure` first if it requires settings. Use `plugin_list` to list all plugins, or `plugin_remove` to uninstall. args: remote - Docker Hub plugin reference, e.g. "vieux/sshfs:latest" local_name - Alias to refer to the plugin locally; defaults to remote returns: dict - The installed plugin's attrs

List installed plugins. returns: list - A list of plugin attrs dicts

Remove a plugin. args: name - The plugin name force - Force removal even if the plugin is enabled returns: bool - True after removal

Upgrade an installed plugin to a newer version. The plugin must be disabled first — call `plugin_disable` before this, then `plugin_enable` afterwards to bring it back up. `remote` lets you upgrade to a different reference (e.g. a newer tag) than the plugin's current name; omit it to re-pull the same reference. Existing settings and volumes created by the plugin persist across the upgrade. args: name - The plugin name to upgrade remote - Reference to upgrade to, e.g. "vieux/sshfs:next" (default: same as name) returns: bool - True after the upgrade completes

Fetch and parse an image's config blob from a registry without pulling. Answers "what's inside this image?" — env vars, entrypoint/cmd, workdir, exposed ports, user, labels, layer history (what `registry_manifest` only points at via `config.digest`). Resolves in up to three hops: manifest -> (if multi-platform) the `platform` entry's manifest -> the config blob. args: repository - Image/repository ref, e.g. "ghcr.io/org/repo"; `:tag`/`@digest` is stripped — pass via `reference` reference - Tag or digest (default "latest") platform - Platform to select from a multi-platform image, "os/arch[/variant]" (default "linux/amd64"); ignored for single-platform images username - Optional registry username (overrides DOCKER_MCP_SERVER_REGISTRY_USERNAME) password - Optional registry password/token (overrides DOCKER_MCP_SERVER_REGISTRY_PASSWORD) returns: dict - {"name", "registry", "reference", "platform", "config_digest", "config": <parsed>}; `platform` is the selected platform (None if single-platform)

Fetch a repository's manifest without pulling. May return a single-platform image manifest or a multi-platform manifest list / OCI image index, depending on what the registry serves for that tag. Talks HTTPS directly — no daemon or CLI needed. Alternatives for the same question: `buildx_imagetools_inspect` (uses the docker CLI and its credential store) and `image_registry_data` (asks the daemon). args: repository - Image/repository ref, e.g. "ghcr.io/org/repo"; `:tag`/`@digest` is stripped — pass via `reference` reference - Tag or digest (default "latest") username - Optional registry username (overrides DOCKER_MCP_SERVER_REGISTRY_USERNAME; no config.json) password - Optional registry password/token (overrides DOCKER_MCP_SERVER_REGISTRY_PASSWORD) returns: dict - {"name", "registry", "reference", "media_type", "digest", "manifest": <JSON body>}

Block until a specific tag appears in a repository (e.g. waiting for a CI push to land). Never raises on timeout — the result always carries `met` and `timed_out`. Polls `registry_tags` every `poll_interval`s and checks whether `tag` is in its result. Works against Docker Hub too (`registry_tags`' own scope covers it), so there is no separate Hub variant. Unlike every other wait tool, this has no `host` argument — registry tools talk HTTPS directly to the registry, not a Docker daemon. Caveat: `registry_tags` paginates up to 50 pages (or `limit` tags, whichever comes first); if `tag` would only appear beyond that window it is never found, even once it exists. Raise `limit` if you expect a very large tag list. args: repository - Image/repository ref, e.g. "alpine", "ghcr.io/org/repo"; any `:tag`/`@digest` is stripped tag - The exact tag name to wait for username - Optional registry username (overrides DOCKER_MCP_SERVER_REGISTRY_USERNAME) password - Optional registry password/token (overrides DOCKER_MCP_SERVER_REGISTRY_PASSWORD) limit - Max tags to scan per poll (default 1000, >= 1); forwarded to `registry_tags` timeout_seconds - Max seconds to wait before returning with timed_out=true (default 600) poll_interval - Seconds between re-checks (default 5, > 0); capped by the time left so a large value can't push the total wait past the timeout returns: dict - {"repository", "tag", "met", "timed_out", "waited_seconds"}

List tags for a repository in an OCI v2 registry without pulling. Works against Docker Hub, GHCR, ECR, GAR, and any OCI-compliant registry; anonymous if no credentials are passed. Talks directly to the registry over HTTPS and does NOT read `~/.docker/config.json` — for private registries prefer the DOCKER_MCP_SERVER_REGISTRY_USERNAME / DOCKER_MCP_SERVER_REGISTRY_PASSWORD env vars (keeps secrets out of tool args, which clients often log). args: repository - Image/repository ref, e.g. "alpine", "ghcr.io/org/repo"; any `:tag`/`@digest` is stripped username - Optional registry username (overrides DOCKER_MCP_SERVER_REGISTRY_USERNAME) password - Optional registry password/token (overrides DOCKER_MCP_SERVER_REGISTRY_PASSWORD) limit - Max tags to return (default 1000, >= 1); pagination capped at 50 pages returns: dict - {"name": <repo>, "registry": <host>, "tags": [..], "truncated": bool}

Compare two image references and report the CVE delta. Exactly one of `to`, `to_env`, or `to_latest=True` must be supplied to identify the comparison target. args: image - The new / candidate image reference to - Compare against this image reference, directory, or archive to_env - Compare against an image associated with this Scout environment to_latest - Compare against the latest scan of `image` only_severity - Filter to severities ("critical", "high", "medium", "low", "unspecified") ignore_unchanged - Exclude unchanged packages from the diff format - Output format: "json" (default), "markdown", or "text" platform - Platform of the image to analyze returns: dict - {"format": <format>, "result": <parsed-json-or-raw-text>, "raw": <CliResult dict>}

List vulnerabilities (CVEs) in an image via Docker Scout. Anonymous scans work for public images; Hub policy enforcement and richer recommendations need `docker login` on the host running this MCP server. args: image - Image reference (a tag or a digest) only_fixed - Only report CVEs with a fixed version available only_severity - Filter to severities: "critical", "high", "medium", "low", "unspecified" ignore_base - Exclude CVEs introduced by the base image format - Output format: "json" (default; parsed into the return dict), "sarif", "spdx", "list", "markdown", or "text" platform - Platform of the image to analyze, e.g. "linux/amd64" returns: dict - {"format": <format>, "result": <parsed-json-or-raw-text>, "raw": <CliResult dict>}

Render a compact summary of an image's CVE posture. args: image - Image reference format - Output format: "json" (default) or "text" platform - Platform of the image to analyze, e.g. "linux/amd64" returns: dict - {"format": <format>, "result": <parsed-json-or-raw-text>, "raw": <CliResult dict>}

Suggest base-image upgrades for an image. Computed against Docker Scout's catalog; generally needs `docker login` on the host running this MCP server to return useful results for private or rarely-scanned base images. args: image - Image reference only_refresh - Only show "refresh" recommendations (same major/minor) only_update - Only show "update" recommendations (newer minor/major) tag - Restrict to suggestions matching this tag pattern format - Output format: "json" (default) or "text" platform - Platform of the image to analyze returns: dict - {"format": <format>, "result": <parsed-json-or-raw-text>, "raw": <CliResult dict>}

Generate a Software Bill of Materials (SBOM) for an image. SBOMs can be large; captured stdout is subject to MAX_CLI_OUTPUT_BYTES and may be truncated for big images. If that's a concern, run `docker scout sbom -o file.json …` on the host and load the file separately. args: image - Image reference format - SBOM format: "spdx" (default, SPDX JSON), "cyclonedx" (CycloneDX JSON), "json" (Scout's native JSON), "list" (plain-text package list) platform - Platform of the image to analyze returns: dict - {"format", "result", "raw": <CliResult dict>}. `result` is a parsed dict when `format` is "spdx"/"cyclonedx"/"json" and stdout parses cleanly; for "list" or a parse failure it's the raw text.

Create a swarm secret. args: name - The name of the secret data - The secret payload labels - Labels to set on the secret driver - Optional secret driver configuration returns: dict - The created secret's attrs

Get a swarm secret's metadata by id or name; requires a swarm manager. The returned attrs never include the secret's actual data (`Spec.Data` is write-only — the daemon accepts it on `secret_create` but never returns it back, by design). Use this to check a secret's `CreatedAt`, `Labels`, or which driver created it, not to read its contents. To see which services reference it, inspect each service's spec via `service_inspect` (there is no server-side filter for "services using this secret"). args: id_or_name - The secret id or name returns: dict - The secret's attrs, excluding the actual secret data

List swarm secrets' metadata; requires a swarm manager. Like `secret_inspect`, results never include secret data, only metadata (name, id, labels, timestamps). Valid filter keys: `id`, `name`, `names`, `label` (key or key=value). args: filters - Narrow the list; omit to return every secret returns: list - A list of secret attrs dicts (data-free)

Remove a Swarm secret; requires a swarm manager. Removing a secret does not immediately affect running service tasks — tasks that already have the secret mounted retain access until they are restarted or the service is updated. Use `service_list` and inspect each service's spec via `service_inspect` to identify services that mount the secret before removing it (service filters do not support filtering by secret reference). args: id_or_name - The secret id or name to remove returns: bool - True after removal

Create a Swarm service; requires a swarm manager node. Use this instead of `container_run` when you need replicated or global scheduling, rolling updates, or automatic restart across the swarm. Common `extra_kwargs` keys: `name` (str), `env` (list of "KEY=VAL"), `mode` ({"Replicated": {"Replicas": N}} or {"Global": {}}), `networks` (list of network names/ids), `endpoint_spec` ({"Ports": [{"PublishedPort": 80, "TargetPort": 8080}]}), `labels` (dict), `restart_policy` ({"Condition": "on-failure", "MaxAttempts": 3}), `resources` ({"Limits": {"NanoCPUs": 500000000, "MemoryBytes": 134217728}}). For anything else docker-py's `ServiceCollection.create` accepts, call `docs_lookup(section="services")` rather than guessing a key name. args: image - Image to run service tasks from (e.g. "nginx:alpine") command - Override the image's default command; string or list of strings extra_kwargs - Additional docker-py ServiceCollection.create keyword arguments returns: dict - The created service's attrs

Get a swarm service by id or name. args: id_or_name - The service id or name insert_defaults - Merge default values into the output returns: dict - The service's attrs

List swarm services. args: filters - Filter by attributes (id, name, label, mode) managed_only - Only return services created by this MCP server (filters on the docker-mcp-server.managed label); combines with any `filters` given returns: list - A list of service attrs dicts

Get a bounded snapshot of a swarm service's logs (never follows). `follow` is intentionally not exposed: the stream is joined into one string before returning, so following would block forever and grow unbounded. Collection is capped at `max_bytes` (ValueError if exceeded) so a noisy service can't OOM the server. The default is a bounded `tail=200`; `tail="all"` returns the whole buffer, which can be huge on long-running services and exceed the agent's context — prefer an integer, or `since`, to constrain output. args: id_or_name - The service id or name details - Show extra details stdout - Include stdout stderr - Include stderr since - Show logs since this Unix timestamp timestamps - Include timestamps tail - Number of lines from the end (default 200), or the literal "all" for everything max_bytes - Abort with ValueError if the buffered logs exceed this many bytes (default 32 MiB) returns: str - Decoded log output

List the tasks of a swarm service. args: id_or_name - The service id or name filters - Filter by id, name, node, label, desired-state returns: list - A list of task dicts

Stop and remove a swarm service. args: id_or_name - The service id or name returns: bool - True after the service is removed

Roll a swarm service back to its previous spec (the docker `service rollback` equivalent). Re-applies the service's `PreviousSpec` — the spec from before the most recent `service_update` / `service_scale`. Raises ValueError if the service has no PreviousSpec (it has never been updated, or was already rolled back). The high-level SDK exposes no rollback, so this reads the current version and previous spec via the low-level APIClient and submits them with the low-level `update_service` API call. args: id_or_name - The service id or name returns: dict - The daemon response (a dict with a "Warnings" key)

Set the desired replica count for a Replicated-mode swarm service. Only applies to services in `Replicated` mode; a `Global` service runs one task per eligible node and has no replica count to set. The swarm scheduler places or removes tasks asynchronously to converge on the new count — this call returns once the update is accepted, not once every task is running. Check progress with `service_ps` or `service_inspect`. For any other spec change (image, env, resources) use `service_update` instead. args: id_or_name - The service id or name replicas - The desired number of running task replicas returns: bool - True once the scale request is accepted

Update a swarm service's configuration, or force a redeploy with no spec change. Pass exactly one of `updates` (fields to change, same parameters as `service_create`) or `force=True` (the `docker service update --force` equivalent: bumps the ForceUpdate counter so the service's tasks redeploy with an unchanged spec — e.g. to reschedule after a node change or re-pull a mutable tag). args: id_or_name - The service id or name updates - Fields to update on the service; exactly one of updates/force force - Redeploy the service without changing its spec; exactly one of updates/force returns: bool - True after the update

Block until a swarm service's tasks converge, or a rolling update finishes. One contract for both modes: never raises on timeout — the result always carries `met` and `timed_out`. "running" polls task state via the same task-counting logic as `service-tasks://{id_or_name}` (not the unconfirmed daemon `ServiceStatus` field) until running tasks reach the desired count (Replicated mode) or every returned task is running (Global mode, which has no fixed target). "update-converged" polls `UpdateStatus.State` until it reaches a terminal value (`completed` or `rollback_completed`); if the service has never been updated (no `UpdateStatus` at all), returns promptly with `met=false` — there's nothing to converge to, same as `container_wait`'s no-healthcheck case. args: id_or_name - The service id or name until - Condition to wait for: "running" (default) or "update-converged" replicas - "running" mode only: override the desired replica count (e.g. right after a same-turn `service_scale` call, before polling reflects the new target) timeout_seconds - Max seconds to wait before returning with timed_out=true (default 600) poll_interval - Seconds between re-checks (default 2, > 0); capped by the time left so a large value can't push the total wait past the timeout returns: dict - {"service", "until", "met", "timed_out", "running_tasks", "desired_tasks", "failed_tasks", "update_state", "waited_seconds"}

Deploy (or update) a stack to the swarm from one or more Compose files. Requires the target daemon to be a swarm manager. Re-running with the same `name` updates the stack in place. Defaults to `detach=True` (returns once specs are submitted, not on convergence); set `detach=False` to wait for the rollout (give it a generous `timeout_seconds`). args: name - Name of the stack to create or update compose_files - One or more Compose file paths (repeated `-c`; later override earlier). At least one required. with_registry_auth - Send registry credentials to swarm agents (needed for private images) prune - Remove services no longer defined in the Compose file resolve_image - Image-digest resolution: "always" (default), "changed", or "never" detach - Return immediately after submitting specs (True) vs wait for convergence (False) cwd - Working directory for resolving relative Compose paths (defaults to the server's cwd) timeout_seconds - Subprocess timeout (default 1800s) returns: dict - {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

List the stacks deployed to the swarm, parsed from `--format '{{json .}}'`. Requires the target daemon to be a swarm manager (raises otherwise). returns: list - One dict per stack (name, services count, orchestrator)

List the tasks of a stack, parsed from `--format '{{json .}}'`. args: name - The stack to list tasks for no_trunc - Do not truncate task IDs / errors in the output filters - Filter by attributes, e.g. {"desired-state": "running"}; a list value repeats the filter returns: list - One dict per task (id, name, node, image, desired/current state, error)

Remove one or more stacks from the swarm (tears down their services, networks, and secrets). Destructive: this stops and deletes every service in the named stack(s). Defaults to `detach=True` so the call returns once removal is requested rather than waiting for teardown. args: names - One or more stack names to remove. At least one is required. detach - Return immediately (True) vs wait for the stack(s) to be fully removed (False) timeout_seconds - Subprocess timeout (default 300s) returns: dict - {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

List the services of a stack, parsed from `--format '{{json .}}'`. args: name - The stack to list services for filters - Filter by attributes, e.g. {"name": "web"}; a list value repeats the filter returns: list - One dict per service (id, name, mode, replicas, image, ports)

Initialize a new swarm, making this Engine its first manager node. Fails if the Engine is already part of a swarm — call `swarm_leave` first to reset it. `advertise_addr` only needs setting when the host has multiple network interfaces or is behind NAT (otherwise it is auto-detected); it must be reachable by every other node that will join. To add more nodes afterwards, retrieve join tokens with `swarm_join_tokens` and call `swarm_join` on each one. Set `autolock_managers=True` to require the unlock key (`swarm_unlock_key`) on every manager restart — store that key securely immediately, since it is only shown once autolock is enabled. args: advertise_addr - Externally reachable address advertised to other nodes listen_addr - Listen address used for inter-manager communication force_new_cluster - Force a new single-node cluster from this node's current state (disaster recovery when a majority of managers is lost) default_addr_pool - IP address pools for swarm overlay networks subnet_size - Subnet size for the IP pool data_path_addr - Address to use for data path traffic data_path_port - Port number for data path traffic name - Name of the swarm labels - Labels to set on the swarm autolock_managers - Require the unlock key after every manager restart log_driver - Default log driver configuration returns: str - The node id of the newly created swarm manager

Inspect the swarm this daemon belongs to (id, spec, join-token config, CA info). returns: dict - The swarm's attrs, as returned by the daemon's swarm inspect endpoint

Join this Engine to an existing swarm as a worker or manager. Fails if the Engine is already part of a swarm. Whether this node joins as a worker or a manager is determined entirely by which token is passed — `join_token` must be one of the two tokens from `swarm_join_tokens`, called against any existing manager. `advertise_addr` only needs setting when this host has multiple network interfaces or is behind NAT (otherwise it is auto-detected from the interface used to reach `remote_addrs`); it must be reachable by every other node in the swarm. args: remote_addrs - Address(es) of existing swarm managers to connect to join_token - The worker or manager join token (from `swarm_join_tokens`) — determines the role this node joins as listen_addr - Listen address for inter-manager communication advertise_addr - Externally reachable address advertised to other nodes data_path_addr - Address to use for data path traffic returns: bool - True after the engine joins the swarm

Return the swarm's worker and manager join tokens. These are the tokens a new node passes to `swarm_join` — without one, `swarm_join` cannot be called, so this closes the init -> join loop. The tokens are secret bearer credentials (anyone holding the manager token can join as a manager); treat the result as sensitive and avoid logging it. Reads `swarm.attrs["JoinTokens"]` after a reload, so it always reflects the current tokens. returns: dict - {"Worker": <worker join token>, "Manager": <manager join token>}

Leave the current swarm. args: force - Force leave even if the node is a manager returns: bool - True after leaving the swarm

Unlock a manager node that is locked after restart due to autolock being enabled. When autolock is enabled (via `swarm_init` or `swarm_update`), manager nodes require the unlock key after every restart before they can rejoin the swarm and resume scheduling. Must be called on the locked manager node directly. Retrieve the current unlock key with `swarm_unlock_key` from any unlocked manager — store it securely when enabling autolock. A locked node cannot serve API requests and cannot return its own key while locked; other unlocked managers in the swarm can still serve the key. Once unlocked the manager resumes automatically. args: key - The swarm unlock key (from `swarm_unlock_key`) returns: bool - True after the swarm is unlocked

Return the swarm's current unlock key. The key only serves a purpose when autolock is enabled (see `swarm_init`'s / `swarm_update`'s `autolock_managers` / `rotate_manager_unlock_key`). Must be called against an unlocked manager — a locked manager cannot serve API requests, including this one. Feed the result's key to `swarm_unlock` to unlock a manager after restart. Treat the key as a sensitive credential. returns: dict - {"UnlockKey": <the current unlock key>}

Update swarm-wide settings: the single home for join-token and unlock-key rotation. 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`. 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 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

Return Docker disk usage information. returns: dict - Data usage information for images, containers and volumes

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 (default 100) timeout_seconds - Max wall-clock seconds before returning what was collected (default 30) returns: list - A list of decoded event dicts (length <= limit)

Return system-wide Docker information. returns: dict - System information from the Docker daemon

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. 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 server response from the login request

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. 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. returns: dict - the rebuilt host's version info (same shape as `system_version`), confirming connectivity