Docker MCP Server

Suspend all processes in a container using the kernel freezer cgroup. Unlike sending SIGSTOP, the freezer cgroup suspends processes without their being able to observe or intercept the suspension. A paused container keeps its resources (memory, open file descriptors) but consumes no CPU. Resume with `container_unpause` — `container_exec` fails against a paused container until it is unpaused. args: id_or_name - The container id or name returns: dict - The container's attrs after pause

Remove all stopped containers to reclaim disk space. Only removes containers that are not running — running containers are never affected. Use `container_list(all=True)` to preview what would be removed before calling this. Valid filter keys: `until` (RFC3339 timestamp or duration like "24h" — removes containers stopped before that point), `label` (key or key=value). For a broader cleanup of containers plus unused images, networks, and volumes see the `prune_managed` prompt. args: filters - Narrow which stopped containers to remove; omit to remove all stopped returns: dict - {"ContainersDeleted": [...], "SpaceReclaimed": <bytes>}

Remove a container. args: id_or_name - The container id or name volumes - Also remove anonymous volumes (the CLI's `--volumes`) link - Remove the specified link force - Force remove a running container returns: bool - True after removal completes

Rename a container. args: id_or_name - The container id or name name - The new name returns: dict - The container's attrs after rename

Restart a container. args: id_or_name - The container id or name stop_timeout_seconds - Seconds to wait for graceful stop before SIGKILL and restart returns: dict - The container's attrs after restart

Run a container from an image. args: image - The image to run command - The command to run in the container name - Name to assign to the container detach - Run in the background and return container info environment - Environment variables to set ports - Port mappings, e.g. {'2222/tcp': 3333} volumes - Volumes to mount network - Name of the network to attach hostname - Optional hostname for the container user - Username or UID to run as working_dir - Working directory inside the container entrypoint - Entrypoint to override the image default restart_policy - Restart policy, e.g. {'Name': 'on-failure', 'MaximumRetryCount': 3} labels - Labels to set on the container remove - Remove the container when it exits (only with detach=False) auto_remove - Enable auto-removal of the container on daemon side privileged - Give extended privileges to the container tty - Allocate a pseudo-TTY stdin_open - Keep STDIN open mem_limit - Memory limit cpu_count - Number of CPUs extra_kwargs - Additional keyword arguments forwarded to ContainerCollection.run (call `docs_lookup(section="containers")` for the full accepted set) returns: dict | str - Container attrs when detach=True, otherwise stdout/stderr as a string

Start an existing stopped container. Use this to restart a container that was previously created or stopped without removing it. To create and start a new container in one step use `container_run` instead. Calling on an already-running container has no effect (the daemon returns 304 and no error is raised). To stop then start a running container use `container_restart`. args: id_or_name - Container id (full or short) or name returns: dict - The container's full attrs after starting

Get a single resource usage stats snapshot for a container. args: id_or_name - The container id or name returns: dict - Decoded stats snapshot

Stop a container. args: id_or_name - The container id or name stop_timeout_seconds - Seconds to wait for graceful stop before SIGKILL returns: dict - The container's attrs after stop

Show the running processes inside a container. args: id_or_name - The container id or name ps_args - Arguments to pass to ps inside the container returns: dict - Output of the top command

Resume all processes in a paused container. args: id_or_name - The container id or name returns: dict - The container's attrs after unpause

Update resource limits on a container without recreating it. Changes take effect immediately on Linux (cgroups); not all fields are updatable on every platform. Common `updates` keys: `mem_limit` (bytes, e.g. 134217728 for 128 MB), `memswap_limit` (memory+swap in bytes; -1 = unlimited), `cpu_shares` (relative weight, default 1024), `cpu_period` / `cpu_quota` (microseconds for CFS throttling), `cpuset_cpus` (e.g. "0-1"), `restart_policy` (dict with `Name` such as "on-failure"/"always"/"unless-stopped" and optional `MaximumRetryCount`). To change image, env, or volumes the container must be recreated. args: id_or_name - Container id or name to update updates - Resource fields to update; see description for valid keys returns: dict - The container's full attrs after the update

Block until a container reaches a condition: stopped, "healthy", or its logs contain a pattern. One contract for every mode: never raises on timeout — the result always carries `met` (condition reached) and `timed_out`. The stop conditions ("not-running"/"next-exit"/"removed") use the daemon's blocking wait and fill `status_code`/`error` (the container's exit info); "healthy" polls the container's HEALTHCHECK every `poll_interval`s and fills `health`/`status`; "log-match" polls recent logs every `poll_interval`s for `pattern` and fills `matched_line`. Health semantics: with no HEALTHCHECK defined, once the container is `running` the tool returns promptly with `health: null` and `met: false` (false = "not confirmed healthy", not "unhealthy" — check `health` to tell them apart). A container that exits before becoming healthy returns its terminal `status` and `met: false`. Log-match semantics: `pattern` is matched as a **plain substring** by default — safe against any input, including adversarial ones. Pass `regex=True` to match `pattern` as a regular expression (via `re.search`) instead; only do this with patterns you trust, since a regex with catastrophic backtracking run against attacker-influenced log content can exhaust CPU (ReDoS). Checks stdout and stderr, most recent lines first within each poll. If the container exits/dies before the pattern ever appears, returns promptly with `met=false` (not `timed_out`) — no further logs can arrive, so there's nothing to keep polling for. args: id_or_name - The container id or name until - Condition to wait for: "not-running" (default), "next-exit", "removed", "healthy", or "log-match" (requires `pattern`) timeout_seconds - Max seconds to wait before returning with timed_out=true (default 600) poll_interval - "healthy"/"log-match" only: seconds between re-checks (default 2, > 0); capped by the time left so a large value can't push the total wait past the…

Create a new Docker CLI context pointing at a daemon endpoint. args: name - Name for the new context (must not already exist) docker_host - Daemon URL, e.g. "tcp://10.0.0.5:2376" or "unix:///var/run/docker.sock" description - Optional human description shown in `context ls` tls_ca - Path on the local host to the CA cert (for TLS daemons) tls_cert - Path on the local host to the client cert tls_key - Path on the local host to the client key skip_tls_verify - Disable TLS verification (insecure; for testing only) returns: dict - {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Return the full configuration for a single Docker context. args: name - Context name (use the `Name` field from `context_list`) returns: dict - The parsed `docker context inspect` entry for that context

List Docker CLI contexts known to the host running this MCP server. Contexts are a CLI concept (stored in the docker config dir) letting one CLI target multiple daemons. This server uses whatever DOCKER_HOST / current-context resolved to at startup, so changing contexts only affects future subprocess-based tools, not the docker-py SDK client. returns: list - One dict per context with at least name, description, dockerEndpoint, and current

Remove a Docker CLI context. args: name - Context name to remove force - Force removal even if the context is the current one returns: dict - {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Set the active Docker context for the CLI on the host running this MCP server. Note: this does not retarget the long-lived docker-py client — SDK-backed tools keep using the endpoint they connected to at startup. To retarget those, restart the server with a different DOCKER_HOST / DOCKER_CONTEXT. args: name - Existing context name to set as default returns: dict - {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Look up Docker SDK/CLI/registry reference documentation by section. A tool-callable mirror of the docker-docs:// resources, for clients that can't read MCP resources (e.g. Claude Desktop, Cursor). Always registered regardless of DOCKER_MCP_SERVER_DISABLE — looking something up costs nothing and isn't tied to any single Docker feature area — but an individual section still refuses if the domain it documents is disabled, matching the equivalent `docker-docs://{section}` resource exactly. Omit `section` to list every available section with its source URL (same as `docker-docs://contents`); pass a `section` name to fetch that page's content (same as `docker-docs://{section}`). Most useful before constructing an `extra_kwargs`-style passthrough dict for a tool like `container_run`/`container_create`/`service_create` (their docstrings only list common keys, not every key docker-py accepts), or before writing Compose/Dockerfile/buildx bake-file syntax, which no tool generates. args: section - Section name (from a no-argument call's index); omit to list all sections instead returns: str - JSON section index (no `section`) or that section's raw HTML/Markdown content

List the Docker hosts configured via DOCKER_MCP_SERVER_HOSTS. With a single host (or the var unset) this is the one resolved daemon; with several it is the set the `host` argument selects from. The `default` entry is the one used when `host` is omitted. returns: list[dict] - one per host: name; url (resolved daemon URL, null = docker-py platform default); read_only; tls (whether a per-host cert dir is configured); default (the omitted-host fallback)

Report the caller's remaining Docker Hub pull-rate-limit budget. Sends a HEAD to the `ratelimitpreview/test` manifest (a HEAD isn't metered as a pull, so the check costs no budget) and reads the RateLimit-Limit / RateLimit-Remaining headers. Call it before a large `compose_pull` / `image_pull` to avoid hitting the cap mid-deploy. Credentials raise the limit and switch metering from per-IP to per-account; falls back to DOCKER_MCP_SERVER_REGISTRY_USERNAME / DOCKER_MCP_SERVER_REGISTRY_PASSWORD, does NOT read `~/.docker/config.json`. Plans with no limit return no headers — reported as `"unlimited": true`. args: username - Optional Hub username (overrides DOCKER_MCP_SERVER_REGISTRY_USERNAME) password - Optional Hub password/token (overrides DOCKER_MCP_SERVER_REGISTRY_PASSWORD) returns: dict - {"authenticated", "limit", "remaining", "window_seconds", "unlimited"}

Fetch Docker Hub metadata for a repository. Public repos only: sends no auth and does NOT read the local Docker credential store; private repos return 404/401. args: repository - Hub repository, e.g. "library/alpine" or "myorg/myimage" returns: dict - The Hub /v2/repositories/<repo>/ response (description, star_count, pull_count, last_updated, is_private, etc.)

List tags on a Docker Hub repository with Hub-specific metadata. Hits the Hub UI API (hub.docker.com) for richer per-tag data than `registry_tags` — last pushed date, per-platform sizes, digest. Public repos only: sends no auth and does NOT read `~/.docker/config.json`; private repos return 404/401 (use `registry_tags` against registry-1.docker.io with credentials). args: repository - Hub repository, e.g. "library/alpine" or "myorg/myimage" limit - Max tags to return (default 100, >= 1); pagination capped at 50 pages returns: dict - {"name": <repo>, "tags": [{name, full_size, last_updated, digest, images}, ...], "truncated": bool}

Build an image from a Dockerfile using the daemon's classic builder. Use this for simple single-platform builds from a local context. For multi-platform builds, BuildKit cache export/import, or advanced build features prefer `buildx_build`. `path` must be a directory accessible on the host running this server (it is the build context sent to the daemon). `dockerfile` is relative to `path`; omit to use the default `Dockerfile`. args: path - Build context directory path on the server host tag - Name and optional tag in "name:tag" format to apply to the built image quiet - Suppress verbose build output (final image id still returned) nocache - Ignore the layer cache and rebuild all layers rm - Remove intermediate containers on success (default True) pull - Always pull a newer version of each FROM base image before building forcerm - Remove intermediate containers even on build failure dockerfile - Dockerfile filename relative to path (default: "Dockerfile") buildargs - Build-time variables passed as `--build-arg`; dict of str→str container_limits - Resource limits for the build container, e.g. {"memory": 134217728} shmsize - Size of /dev/shm in bytes for build steps that need shared memory labels - Labels to set on the resulting image (dict of str→str) cache_from - List of image references to use as layer cache sources target - Stop at this named build stage (multi-stage Dockerfiles) network_mode - Network mode for RUN instructions during build (e.g. "host", "none") squash - Squash all new layers into one (experimental; requires daemon flag) extra_hosts - Additional /etc/hosts entries during build; dict of hostname→ip platform - Target platform, e.g. "linux/amd64" (single platform only; use buildx for multi) isolation - Windows isolation technology ("default", "process", "hyperv") use_config_proxy - Forward proxy env vars from Docker client config to build returns: dict - The built imag…

Return the layer history of an image. Useful for auditing what commands built each layer and diagnosing image size. Each entry includes `Id` (layer digest or "<missing>" for imported layers), `Created` (unix timestamp), `CreatedBy` (the Dockerfile command that produced the layer, e.g. a RUN or COPY), `Size` (bytes added by that layer), and `Comment`. For full image metadata use `image_inspect` instead. args: id_or_name - Image name (with optional tag/digest) or id returns: list - Layer history entries, newest first

Return the full inspect detail for a single local image. Includes config (env, entrypoint, exposed ports), size, layer digests (`RootFS.Layers`), and all tags/digests referencing it (`RepoTags`/`RepoDigests`). For a quick overview of many images use `image_list` instead. For the per-layer build history (which command produced each layer) use `image_history`. Only inspects images already present locally — for a remote image's manifest without pulling it use `image_registry_data` or `registry_manifest`. args: id_or_name - Image name (with optional tag/digest) or id returns: dict - Full image inspect attrs (equivalent to `docker inspect` on an image)

List images on the server. args: repository - Only show images of this repository all - Show intermediate image layers filters - Filter by attributes (label, dangling, before, since, etc.) returns: list - A list of image attrs dicts

Load an image from a tarball produced by image_save, from in-band bytes or a file on the server host. Pass exactly one of `data` (tarball bytes in band) or `from_file` (a path on the server host, streamed straight to the daemon — preferred for anything but small images, since in-band bytes are base64-encoded by MCP). `from_file` is read by the server's user; `~` is expanded. args: data - Tarball contents; exactly one of data/from_file from_file - Path to a tarball produced by `docker save` / `image_save`; exactly one of data/from_file returns: list - A list of loaded image attrs dicts

Remove unused local images to reclaim disk space. Without filters removes only "dangling" images — untagged layers not referenced by any tag or container. To remove all images not used by any container (including tagged ones) pass `filters={"dangling": False}`. Valid filter keys: `dangling` (bool as string "true"/"false"), `until` (RFC3339 timestamp or duration like "24h"), `label` (key or key=value). Use `system_df` first to see how much space is reclaimable. args: filters - Narrow which images to remove; omit to remove dangling images only returns: dict - {"ImagesDeleted": [...], "SpaceReclaimed": <bytes>}

Pull an image from a registry to the daemon's local store. args: repository - The image repository tag - The image tag (ignored when all_tags=True) all_tags - Pull all tags from the repository platform - Platform in os/arch format returns: dict | list - Pulled image attrs (or a list of attrs if all_tags=True)

Push an image or repository to a registry. Security: `auth_config` carries registry credentials, which many MCP clients log verbatim. Prefer `docker login` on the host so the `docker` module reuses credentials cached in `~/.docker/config.json`, and leave `auth_config` unset. args: repository - The image repository tag - The tag to push auth_config - Optional registry authentication config returns: str - Push output as a string

Get registry data for an image without pulling it, via the daemon's distribution endpoint. Uses the daemon (and its cached credentials) to resolve the remote descriptor and platform list. For direct registry access without a daemon use `registry_manifest`. Security: `auth_config` carries registry credentials, which many MCP clients log verbatim. Prefer `docker login` on the host so the `docker` module reuses credentials cached in `~/.docker/config.json`, and leave `auth_config` unset. args: repository - Image reference auth_config - Optional registry authentication config returns: dict - Registry data attrs

Remove a local image by name or id. Fails without `force` if the image is tagged by multiple names (untag first with `image_tag`) or if stopped containers reference it. Running containers always block removal regardless of `force`. `noprune` keeps untagged parent layers that would otherwise be removed as a side-effect; leave False unless you need to preserve the parent layers for another purpose. args: id_or_name - Image name (with optional tag/digest) or id to remove force - Remove even if referenced by stopped containers or multiple tags noprune - Do not delete untagged intermediate parent layers returns: bool - True after removal completes

Save an image as a tar archive: to a file on the server host, or in band. With `dest_path` the archive streams straight to disk (no byte cap), so it handles large images — the file is written by the server's user, `~` is expanded, and an existing file is refused unless `overwrite=True`. Without `dest_path` the tar bytes are returned in band, capped at `max_bytes` (default 32 MiB) because MCP base64-encodes them — a fallback for when no writable host path exists (e.g. a containerized server without a bind mount). args: id_or_name - Image name or id dest_path - Destination path on the server host; omit to return the bytes in band named - Whether to retain repository/tag names in the saved archive overwrite - Replace dest_path if it already exists (default False) max_bytes - In-band mode: abort with ValueError beyond this many bytes (default 32 MiB) returns: bytes | dict - the tarball bytes (in band), or {"path": <resolved path>, "bytes_written": int}

Search Docker Hub for public images matching a term. Searches Docker Hub only — not GHCR, ECR, or other registries. For listing tags on a specific image from any OCI registry use `registry_tags` instead. Each result dict includes `name`, `description`, `star_count`, `is_official`, and `is_automated`. args: term - Search keyword, e.g. "nginx" or "python" limit - Maximum number of results to return (Docker Hub default is 25) returns: list - List of matching image dicts from Docker Hub

Tag an image into a repository. args: id_or_name - The source image name or id repository - Target repository name tag - Optional tag for the new image force - Force the tag returns: bool - True if the image was tagged

Attach a running container to an additional network without restarting it. Use this to give a container access to services on a network it was not started with. `aliases` sets extra DNS names for this container within the network (other containers can reach it by those names in addition to its container name). `ipv4_address` / `ipv6_address` assign a specific IP on the network; omit to let the driver assign one. `links` is a legacy feature (deprecated; prefer DNS aliases). Use `network_disconnect` to undo. args: id_or_name - Network id or name to connect the container to container - Container id or name to attach aliases - Additional DNS names for this container within the network links - Legacy container links (deprecated) ipv4_address - Static IPv4 address to assign on this network ipv6_address - Static IPv6 address to assign on this network link_local_ips - Link-local IP addresses to assign driver_opt - Driver-specific endpoint options returns: bool - True after the container is connected

Create a network. args: name - The name of the network driver - Driver name (e.g. bridge, overlay) options - Driver-specific options ipam - IPAM configuration as a dict check_duplicate - Reject creation if a duplicate name exists internal - Restrict external access labels - Labels to set on the network enable_ipv6 - Enable IPv6 networking attachable - Allow standalone containers to attach (swarm) scope - Network scope (local, global, swarm) ingress - Make this an ingress network for swarm routing-mesh returns: dict - The created network's attrs

Disconnect a container from a network. args: id_or_name - The network id or name container - The container id or name force - Force disconnect returns: bool - True after the container is disconnected

Return the full inspect detail for a single network. Includes the connected containers (`Containers`, keyed by container id, with each entry's assigned IP), IPAM config, and driver options. For a quick overview of many networks use `network_list` instead — its default (non-`greedy`) response omits the per-network `Containers` detail for speed. args: id_or_name - The network id or name returns: dict - Full network inspect attrs (equivalent to `docker network inspect`)

List networks. Valid filter keys: `driver` (driver name), `label` (key or key=value), `type` ("custom" or "builtin"). `names`/`ids` are a separate shorthand for filtering by exact name/id, applied in addition to `filters`. Set `greedy` to fetch each network's attrs individually (adds the connected-containers detail that `network_inspect` returns, at the cost of one extra daemon call per network) — leave it False for a fast summary list. args: names - Filter by exact network names ids - Filter by exact network ids filters - Additional server-side filters; see description for valid keys greedy - Fetch extended per-network details (including connected containers) managed_only - Only return networks created by this MCP server (filters on the docker-mcp-server.managed label); combines with any `filters` given returns: list - A list of network attrs dicts

Remove networks that have no active container endpoints. Built-in networks (bridge, host, none) are never removed. Only networks with zero connected containers are eligible. Valid filter keys: `until` (RFC3339 timestamp or duration — removes networks created before that point), `label` (key or key=value). args: filters - Narrow which networks to remove; omit to remove all unused custom networks returns: dict - {"NetworksDeleted": [...]}

Remove a single custom network by id or name. Fails if any container is still attached (disconnect with `network_disconnect` or stop the containers first). Built-in networks (`bridge`, `host`, `none`) can never be removed and return an error regardless of attachment state. For bulk cleanup of every unused custom network at once use `network_prune` instead. args: id_or_name - The network id or name returns: bool - True after removal

Get a swarm node by id or name. args: id_or_name - The node id or name returns: dict - The node's attrs

List swarm nodes. args: filters - Filter by attributes (id, name, membership, role) returns: list - A list of node attrs dicts

Remove a node from the swarm. A node should normally be drained (`node_update` with Availability "drain") and have left the swarm first, so its tasks reschedule cleanly. Removing an active/reachable node requires `force=True`. args: id_or_name - The node id or name to remove force - Force removal of an active/reachable node returns: bool - True after the node is removed

Replace a node's spec (availability, name, role, labels). Replacement, not a merge: `spec` becomes the node's entire spec, and omitted keys are cleared. Fetch the current spec via `node_inspect` (its `Spec` key), modify it, and resubmit the whole dict — e.g. sending just {"Availability": "drain"} would also wipe the node's role and labels. args: id_or_name - The node id or name spec - The complete new node spec (see description — omitted keys are cleared) returns: bool - True after the update

Block until a swarm node's Status.State reaches a target value. Never raises on timeout — the result always carries `met` and `timed_out`. Polls `Status.State` (one of "unknown"/"down"/"ready"/"disconnected") every `poll_interval`s. Common uses: `until="ready"` after a newly joined node, or `until="down"` while draining a node before removal. Does not track task placement — for "has this drained node's workload fully moved off", inspect the relevant services' tasks directly; no single cheap call spans every service in the swarm, so that check isn't built into this tool. args: id_or_name - The node id or name until - Target Status.State to wait for: "ready" (default), "down", "disconnected", "unknown" timeout_seconds - Max seconds to wait before returning with timed_out=true (default 300) poll_interval - Seconds between re-inspections (default 2, > 0); capped by the time left so a large value can't push the total wait past the timeout returns: dict - {"node", "until", "met", "timed_out", "state", "availability", "waited_seconds"}

Set runtime configuration options on an installed plugin. Use `plugin_inspect` first to see which keys the plugin exposes under `Settings.Env`; pass those same keys as a plain dict, e.g. `{"DEBUG": "1", "SOCKET": "/run/x.sock"}`. The plugin must be disabled before reconfiguring — call `plugin_disable` first if it is currently active, then `plugin_enable` afterwards to apply the new settings. args: name - Plugin name, e.g. "vieux/sshfs:latest" options - Key/value settings to apply, matching the plugin's declared env keys returns: bool - True after configuration

Disable a plugin so it stops intercepting Docker API calls; the plugin remains installed. A disabled plugin cannot be used by new containers but existing containers that already have it attached are unaffected. Use `force=True` to disable even if active containers are still using it — this may cause those containers to lose access to plugin-provided resources (e.g. a volume driver). Re-enable with `plugin_enable`. args: name - The plugin name force - Disable even if active containers are using the plugin (may disrupt them) returns: bool - True after the plugin is disabled