Docker MCP Server

Build multiple targets defined in a bake file (HCL, JSON, or compose). Use it for multi-target builds declared in `docker-bake.hcl`/compose files; for a single Dockerfile target use `buildx_build`. Does not raise on a non-zero CLI exit (a missing buildx plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: targets: Bake targets to build (default: the `default` group) files: Bake file paths (`-f`, repeatable) set_overrides: Per-target overrides, e.g. ["app.platform=linux/amd64"] push: Push results to the registry load: Load results into the local image store no_cache: Do not use cache when building pull: Always pull a newer base image builder: Override the active builder cwd: Working directory containing the bake file (defaults to the server's cwd; copied to the target host if no local plugin) timeout_seconds: Subprocess timeout (default 1800s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Build an image with BuildKit via `docker buildx build`. Replaces the legacy `image_build` tool when you need any of: multi-platform output (`platforms`), modern cache export (`cache_from`/`cache_to`), SBOM or provenance attestations, build secrets, or multi-stage builds with `target`. Always runs with `--progress=plain` so output is captured rather than redrawn on a TTY. With no local buildx plugin and an `ssh://` target, the build runs on that host: a local `context` directory is copied there honouring `.dockerignore`, as are `file`, `build_contexts` and `secret` paths. Raises ToolInputError in that case for `output`/`cache_to` with a filesystem `dest=`, `cache_from` with a local `src=`, or any `ssh=` - each would resolve on the remote machine, losing the output or silently changing the build. Does not raise on a non-zero CLI exit (a missing buildx plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: context: Build context: a filesystem path or Git/HTTP URL (verbatim; no `~`/glob expansion). The `-` stdin-tarball form is NOT supported (stdin isn't forwarded - it'd block on the server's own stdin); serve a pre-packed tarball over HTTP instead. Copied to the target host when it names a local directory and there is no local plugin. tags: Image references to apply (`-t`, repeatable) platforms: Target platforms, e.g. ["linux/amd64", "linux/arm64"] file: Dockerfile path. A relative path resolves against this server's working directory (buildx's own rule), NOT against `context` - pass e.g. "ctx/Dockerfile" for a Dockerfile inside the context directory "ctx". build_args: Build-time variables (each becomes `--build-arg KEY=VALUE`) build_contexts: Additional named build contexts (e.g. {"deps": "./vendor"}) labels: Labels to set on the resulting image (each becomes `--label KEY=VALUE`) annotations: OCI manifest annotations (passed verbatim, repeatable) target: Target build stage to stop at push: Push the result to the registry (mutually exclusive with `load`) load: Load the result into the local image store (single-platform builds only) output: Custom `--output` specs (e.g. ["type=tar,dest=out.tar"]). A filesystem `dest=` is refused when the build has to run on a remote host; `dest=-` (stdout) is fine. no_cache: Do not use cache when building no_cache_filter: Stage names to exclude from caching pull: Always attempt to pull a newer version of each base image cache_from: Cache import specs, e.g. ["type=registry,ref=user/img:cache"] cache_to: Cache export specs builder: Override the active builder sbom: Shorthand for `--attest=type=sbom`; pass "true" or a config string provenance: Shorthand for `--attest=type=provenance`; pass "true", "false", or a config string attest: Custom attestation specs (repeatable) secret: Secret specs (e.g. ["id=npmrc,src=/home/user/.npmrc"] or ["id=npmrc,env=NPM_TOKEN"]). `~` in `src=` is NOT expanded (by this tool or the CLI) - use an absolute path. ssh: SSH agent socket/key specs (e.g. ["default"], using $SSH_AUTH_SOCK). Refused when the build has to run on a remote host: the socket read would be that host's. timeout_seconds: Subprocess timeout (default 1800s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Create a new BuildKit builder instance. Needed when the default `docker` driver falls short: multi-platform builds and cache export require a `docker-container` (or `kubernetes`/`remote`) builder. Pass `use=True` to make it the default for later `buildx_build` calls (else switch with `buildx_use`); `bootstrap=True` starts the builder now rather than on first build. Does not raise on a non-zero CLI exit (a missing buildx plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: name: Name for the new builder (defaults to a generated name) driver: BuildKit driver (e.g. "docker-container", "kubernetes", "remote") driver_opts: Driver-specific options (each becomes `--driver-opt KEY=VALUE`) use: Set the new builder as the current one bootstrap: Boot the builder immediately platforms: Platforms the builder advertises config: Path to a buildkitd config file (copied to the target host if no local plugin); passed as `--buildkitd-config`, so this argument needs buildx >= 0.17 node_name: Node name within the builder (for multi-node builders) append: Append a node to an existing builder named `name` Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Report BuildKit cache disk usage as a list of records. A large cache can easily generate more output than MAX_CLI_OUTPUT_BYTES; if that happens the captured stdout is truncated and this tool drops the final (partial) record before parsing. For an exhaustive accounting on a busy builder, run `docker buildx du --format '{{json .}}'` on the host directly. Reclaim the cache with `buildx_prune` (`system_df` covers daemon-side disk, not builder cache). Raises RemoteFailureError if the CLI call fails. Args: builder: Override the active builder Returns: list: One dict per cache record (parsed from `--format '{{json .}}'`)

Inspect a single build record by ref, parsed from `--format json`. Returns the full record for one build - duration, materials, attestations, error (if any) - for debugging a failed or slow build found via `buildx_history_list`. Requires buildx >= v0.13. Raises RemoteFailureError if the CLI call fails. Args: ref: Build record ref. Pass the `ref` field from `buildx_history_list` directly - it reports a qualified "<builder>/<node>/<id>", but `history inspect` only accepts the bare id, so this reduces it to the id and (unless `builder` is given) targets the builder named in the ref. Empty/omitted inspects the most recent build; the `^N` syntax (e.g. "^0" = latest) is also valid. builder: Builder instance the build ran on (defaults to the one in `ref`, else active) Returns: dict: The parsed build record (or {"raw": <stdout>} if the output isn't a JSON object)

List recent build records (BuildKit build history), parsed from `--format '{{json .}}'`. Each record is a past build with its ref, name, status, step counts, and timestamps - useful for finding a build to drill into with `buildx_history_inspect`. Requires buildx >= v0.13 (older versions have no `history` subcommand and this raises with the CLI's "unknown command" error). Raises RemoteFailureError if the CLI call fails. Args: builder: Builder instance to read history from (defaults to the active builder) Returns: list: One dict per build record (ref, name, status, total/completed/cached steps, times)

Create a manifest list / OCI image index from existing per-platform tags. Replaces `docker manifest create` + `docker manifest push` - builds the index and pushes it in one operation. Source tags must already be pushed; this only stitches them together. Verify the result with `buildx_imagetools_inspect`. Does not raise on a non-zero CLI exit (a missing buildx plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: target: Tag for the new manifest list (`-t`) sources: Source image references to combine append: Append to the existing manifest at `target` rather than replacing dry_run: Print the resulting manifest without pushing annotations: OCI annotations (repeatable; passed verbatim) platforms: Filter source platforms when combining descriptor_files: Files to read source descriptors from, instead of refs (copied to the target host if no local plugin) builder: Override the active builder timeout_seconds: Subprocess timeout (default 600s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Inspect a manifest in a registry without pulling. Replaces `docker manifest inspect`. The standalone `docker manifest` command is in maintenance mode and lacks support for OCI image indexes, attestations, and annotations - `buildx imagetools inspect` is the path forward and handles both single-platform manifests and multi-platform manifest lists / OCI indexes. Uses the docker CLI's credential store; `registry_manifest` answers the same question over direct HTTPS with no daemon or plugin. Does not raise on a non-zero CLI exit (a missing buildx plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: image: Image reference, e.g. "alpine:3.19" or "ghcr.io/org/repo@sha256:..." raw: Return the raw manifest bytes (a JSON document) instead of the human-rendered tree format: Go template format string (mutually exclusive with `raw`) builder: Override the active builder Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}. With `raw=True` or `format="{{json .}}"`, `stdout` is a JSON document the caller can parse.

Inspect a builder instance. Human-readable detail (driver, status, supported platforms) for one builder; `buildx_list` returns machine-parsed JSON for all builders. Does not raise on a non-zero CLI exit (a missing buildx plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: name: Builder name (defaults to the active builder) bootstrap: Boot the builder if it isn't already running Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}. stdout is human-readable; parse with the agent or call buildx_list for JSON.

List builder instances. Machine-parsed view of every builder; use `buildx_inspect` for one builder's human-readable detail and `buildx_use` to switch the default. Raises RemoteFailureError if the CLI call fails. Returns: list: One dict per builder (parsed from `--format '{{json .}}'`). If the captured stdout was truncated by MAX_CLI_OUTPUT_BYTES the last (likely partial) record is dropped before parsing.

Remove BuildKit cache entries. Destructive: this tool always passes `--force` because no interactive prompt is available under MCP. Pair with `buildx_du` first to inventory what would be removed. Does not raise on a non-zero CLI exit (a missing buildx plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: all: Include internal/frontend images filters: Filter by attributes (e.g. {"until": "24h", "type": "exec.cachemount"}) reserved_space: Amount of disk to always keep (e.g. "10GB") max_used_space: Maximum disk space the cache may use (e.g. "20GB") min_free_space: Target amount of free disk after pruning (e.g. "5GB") builder: Override the active builder timeout_seconds: Subprocess timeout (default 600s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Remove a builder instance. Deletes a builder made by `buildx_create`, including its build cache unless keep_state=True; use `buildx_prune` to reclaim cache while keeping the builder. Does not raise on a non-zero CLI exit (a missing buildx plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: name: Builder name to remove (mutually exclusive with `all_inactive`) all_inactive: Remove every inactive builder keep_state: Keep the BuildKit state volume keep_daemon: Keep the BuildKit daemon process running force: Force removal even if the builder is in use Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Select the active builder for subsequent buildx operations. Without `default` or `global_default` the switch applies only to the current CLI session. `default` persists the choice for the current Docker context; `global_default` persists across all Docker contexts. Use `buildx_list` to see available builders and their current status. To avoid switching the global default, pass a specific builder name directly via `buildx_build`'s `builder` parameter instead. Does not raise on a non-zero CLI exit (a missing buildx plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: name: Builder name to activate (from `buildx_list`) default: Persist as default builder for the current Docker context global_default: Persist as default builder across all Docker contexts Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Build images for a compose project. Builds the images declared by the project's `build:` sections without starting anything - `compose_up(build=True)` builds and starts in one step. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override services: Specific services to build (default: all) pull: Always attempt to pull a newer base image no_cache: Do not use cache when building timeout_seconds: Subprocess timeout (default 1800s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Render the canonical compose configuration after merges, profiles, and variable substitution. Use it to validate compose files and see exactly what the CLI will run before `compose_up`. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises): on a failed render `config` may be None - inspect `raw.stderr`. Args: project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override profiles: Profiles to activate before rendering services_only: List service names only (`--services`) format: Render as YAML (default) or JSON Returns: dict: {"config": str|dict|None, "raw": <CliResult dict>}; `config` is a parsed dict when format="json" and parsing succeeds, otherwise the rendered text from stdout.

Copy files/folders between a service container and the server host's filesystem. Exactly one of `source`/`dest` is `SERVICE:PATH`; the other is a path on the host running this MCP server, read/written as the server's user (same host exposure as the file-path archive tools - see SECURITY.md). Copying to stdout (`dest="-"`) is unsupported; use `container_archive_get`. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. With no local compose plugin and an `ssh://` target, runs the real `docker compose cp` on that host instead and relays whichever side of the copy is local over the same SSH connection - every parameter above behaves the same either way, since the actual copy always runs through the real CLI. The one difference: a container->host copy is refused if the local destination already exists, since only this host (not the remote one) knows that. `unix://`/`tcp://`+TLS hosts with no local plugin are not covered by this fallback (no shell to run the CLI on) and still raise `CapabilityError` - use `container_archive_put` (host to container) or `container_archive_get_to_file` (container to host) there instead; both talk to the daemon directly and need no local CLI (`compose_ps` gives you the container name). Args: source: `SERVICE:SRC_PATH` or a host path dest: `SERVICE:DEST_PATH` or a host path (not "-") index: Container index when the service has multiple replicas all_containers: Copy to/from all containers of the service (`--all`) project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override timeout_seconds: Subprocess timeout (default 300s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Stop and remove containers, networks (and optionally volumes) for a compose project. Inverse of `compose_up`. Images are kept; named volumes go only with volumes=True (destructive). Use `compose_stop` to stop without removing anything. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override volumes: Also remove named volumes declared by the project (destructive) remove_orphans: Remove containers not declared in the compose file timeout_seconds: Subprocess timeout (default 300s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Run a command inside an already-running compose service container (see also `container_exec`). Always passes `-T` (no TTY). Pass an exec-form argv (e.g. `["python", "-V"]`); a `["sh", "-c", "..."]` form interprets shell metacharacters in untrusted substrings. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: service: Service name from the compose file command: Argv to execute inside the container project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override index: Container index when the service has multiple replicas workdir: Working directory inside the container user: User to run as inside the container (uid or name) env: Environment variables to set for the exec session timeout_seconds: Subprocess timeout (default 60s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

List the images used by a compose project's services, parsed from `--format json`. Answers "what image and tag does each service container actually run?" - the containers must exist (`compose_up` first). Use `compose_ps` for container state and `image_list` for daemon-wide images. Raises RemoteFailureError if the CLI call fails. Args: project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override services: Restrict to these services (default: all) Returns: list: One dict per container image (service, container, repository, tag, id, size)

Send a signal to a compose project's containers (default SIGKILL). Immediate, with no grace period - prefer `compose_stop` for a clean shutdown (stop signal, then kill after a timeout). Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: services: Restrict to these services (default: all) signal: Signal to send (default "SIGKILL"; e.g. "SIGTERM", "SIGHUP") remove_orphans: Also remove containers for services not in the compose file project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

List compose projects known to the daemon (across all directories). Project-level view (one entry per project); `compose_ps` lists the containers of a single project. Raises RemoteFailureError if the CLI call fails. Args: all: Include stopped projects Returns: list: One dict per project (parsed from `--format json`)

Fetch a bounded slice of logs from a compose project (never follows). Bounded and non-following by design, so it always returns promptly. For one container's logs use `container_logs`; for a swarm service use `service_logs`. Log text arrives on `stdout`. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override services: Restrict to these services (default: all) tail: Lines per container, or the literal "all" (still capped at MAX_CLI_OUTPUT_BYTES) since: Show logs since this timestamp/duration (e.g. "10m", "2024-01-01T00:00:00") until: Show logs before this timestamp/duration timestamps: Include per-line timestamps Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Pause the containers of a compose project (freezes their processes in place). Paused containers stop consuming CPU but keep memory, network endpoints, and state; resume with `compose_unpause`. To actually stop containers (each one's configured stop signal, freeing resources) use `compose_stop`; to stop and delete them use `compose_down`. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: services: Restrict to these services (default: all) project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Resolve the host binding for a service's container port. The compose equivalent of `docker port`: which host address/port a service's private port is published on. `published` is None when the port isn't published. For non-compose containers read `container_inspect`'s NetworkSettings.Ports instead. Raises RemoteFailureError if the CLI call fails. Args: service: Service name from the compose file private_port: The container-internal port to look up protocol: "tcp" (default) or "udp" index: Container index when the service has multiple replicas project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override Returns: dict: {"service", "private_port", "protocol", "published": "host:port"|None, "host": str|None, "port": int|None, "bindings": list[str]}. `published`/`host`/`port` describe the first binding; `bindings` lists every line (a port can be published on more than one address, e.g. IPv4 and IPv6).

List containers in a compose project, parsed from `--format json`. Container-level view of one project (state, health, publishers); `compose_list` enumerates projects, and `container_list` covers non-compose containers. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises): `services` comes back empty - inspect `raw.stderr`. Args: project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override services: Restrict output to these services all: Include stopped containers as well Returns: dict: {"services": list[dict], "raw": <CliResult dict>}; on non-zero exit `services` is an empty list and the caller should inspect `raw.stderr`.

Pre-fetch images for a compose project's services without starting them. Use this to stage images before an outage window, to refresh cached images before `compose_up`, or to verify images are accessible without starting containers. For registry-authenticated pulls ensure the daemon is logged in first with `system_login`. `compose_up --pull always` does the same as part of startup; use this tool when you want to separate the pull step. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`; overrides auto-discovery) project_name: Override the compose project name services: Pull only these services; omit to pull all ignore_pull_failures: Continue if an individual image pull fails timeout_seconds: Subprocess timeout (default 1800s for large image pulls) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Stop then start services without recreating containers or applying config changes. Use this to bounce a service (e.g. to pick up a runtime file change or clear an in-memory state). If the compose file has changed (new image, environment, volumes, ports) use `compose_up` instead - it recreates affected containers to apply the diff. `stop_timeout_seconds` controls the SIGTERM grace period before Docker sends SIGKILL. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Override the compose project name services: Restart only these services; omit to restart all stop_timeout_seconds: Seconds to wait for graceful stop before SIGKILL timeout_seconds: Subprocess timeout (default 300s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Run a one-off command against a compose service. Always passes `-T` (no TTY under MCP). Defaults to detached with `--rm` so the call returns promptly. Unlike `compose_exec`, this starts a NEW container for the service rather than running inside the existing one. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: service: Service name from the compose file command: Command + args to run (exec-form; no shell unless you invoke one) project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override detach: Run detached rm: Remove the container after the run no_deps: Don't start linked services workdir: Working directory inside the container user: User to run as inside the container (uid or name) env: Environment variables to set inside the container name: Container name timeout_seconds: Subprocess timeout (default 600s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Start existing (stopped) containers of a compose project. Counterpart to `compose_stop`: starts existing containers without recreating them. Use `compose_up` to (re)create containers from the compose file. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override services: Specific services to start (default: all) timeout_seconds: Subprocess timeout (default 600s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Stop services in a compose project without removing their containers. Unlike `compose_down`, containers/networks/volumes survive - use `compose_start` to bring them back. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override services: Specific services to stop (default: all) stop_timeout_seconds: Grace period before SIGKILL (passed as `--timeout`) timeout_seconds: Subprocess timeout (default 300s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Show the running processes of a compose project's containers. Output is the `ps`-style process table per service (not JSON); read it from `stdout`. The per-container equivalent is `container_top`. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: services: Restrict to these services (default: all) project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Unpause the containers of a compose project (resumes paused processes). Reverse of `compose_pause`: processes continue from where they were frozen (no restart). `compose_start` is the counterpart for stopped containers. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: services: Restrict to these services (default: all) project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Bring up a Docker Compose project, detached. Always runs detached (`-d`) so it can't block the server. Use `compose_ps` to confirm services are running, or `wait=True` to block until they're healthy. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: project_dir: Dir with the compose file (default: server cwd, copied to the target host if no local plugin; paths verbatim, no shell expansion) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override services: Specific services to bring up (default: all) build: Build images before starting pull: Pull strategy; omit to use each service's own `pull_policy` remove_orphans: Remove containers for services not in the compose file wait: Block until services are healthy (adds `--wait`) timeout_seconds: Subprocess timeout (default 600s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Block until the named service containers stop, then return their exit codes. For one-shot / batch services. A long-running service that never exits blocks until `timeout_seconds`, then the subprocess is killed (TimeoutExpired) - bound it sensibly. Exit codes are on stdout. For a single container use `container_wait`; for swarm services use `service_wait`. Does not raise on a non-zero CLI exit (a missing compose plugin or a timeout still raises) - inspect `returncode`/`stderr` in the result. Args: services: One or more services to wait on. At least one is required. project_dir: Dir with the compose file (default: server cwd; copied to the target host if no local plugin) files: Explicit compose file paths (repeatable, `-f`) project_name: Compose project name override timeout_seconds: Subprocess timeout (default 300s) Returns: dict: {"returncode": int, "stdout": str, "stderr": str, "truncated": bool}

Create an immutable Swarm config object; requires a swarm manager. Configs store non-sensitive configuration files (nginx.conf, app.yaml, etc.) and mount them into service containers at a specified path. Unlike secrets, config data is not encrypted at rest - use `secret_create` for credentials or keys. `data` is raw bytes; encode strings first (e.g. `"my config".encode()`). Once created, a config is immutable: to update it, create a new config with a new name and update the service to reference it, then remove the old config with `config_remove`. Args: name: Unique config name within the swarm data: Raw bytes content of the config file labels: Labels to set on the config templating: Templating driver config (e.g. {"Name": "golang"} for Go template syntax) Returns: dict: The created config's full document ({"ID", "Version", "CreatedAt", "Spec", ...})

Get a swarm config's full inspect payload by id or name. Requires a swarm manager. Unlike a secret, a config's payload IS readable after creation: `Spec.Data` in the result holds the base64-encoded contents. Use `config_list` to enumerate configs; use this to read one config's contents and metadata. Returns: dict: The config's full document (ID, CreatedAt, UpdatedAt, Spec{Name, Labels, Data base64})

List swarm configs; requires a swarm manager. Unlike secrets, config attrs include the actual config data (`Spec.Data`, base64-encoded) since configs are not treated as sensitive. Valid filter keys: `id`, `name`, `names`, `label` (key or key=value). Fetch a single config by id/name with `config_inspect`. Args: filters: Narrow the list; omit to return every config Returns: list: One full config document ({"ID", "Spec", ...}) per config

Remove a swarm config. Requires a swarm manager, and fails while any service still references the config - update or remove those services first. The last step of the rotation flow described in `config_create`. Returns: bool: True after removal

Retrieve a file or directory from a container as a tar archive, returned in band. In-band bytes are capped (default 32 MiB) because MCP base64-encodes them; `container_archive_get_to_file` streams to a host path instead. Args: path: Path inside the container max_bytes: Abort with ToolInputError if the archive exceeds this many bytes (defaults to 32 MiB) Returns: dict: Mapping with archive (bytes) and stat (dict) keys

Retrieve a file or directory from a container as a tar archive written to a file on the server host. File-writing variant of `container_archive_get` - prefer it for anything large, since in-band bytes are base64-encoded by MCP. For the whole filesystem use `container_export`. Streams straight to disk (no in-band byte cap). The file is written by the server's user; `~` is expanded and an existing file is refused unless `overwrite=True`. Args: path: Path inside the container dest_path: Destination path on the server host for the tarball overwrite: Replace dest_path if it already exists Returns: dict: {"path": <resolved path>, "bytes_written": int, "stat": dict}

Upload a tar archive to a path inside a container, from in-band bytes or a file on the server host. Inverse of `container_archive_get`: the archive is extracted at `path` inside the container. Pass exactly one of `data` (tar bytes in band) or `from_file` (a path on the server host, streamed straight to the daemon - preferred for large archives, since in-band bytes are base64-encoded by MCP). `from_file` is read by the server's user; `~` is expanded. Args: path: Destination path inside the container (must already exist) data: Tar archive bytes; exactly one of data/from_file from_file: Path on the server host to the tar archive to upload; exactly one of data/from_file Returns: bool: True if the upload succeeded

Snapshot a container's current filesystem state as a new image. Useful for capturing a debugging state or saving manual changes made inside a container. For repeatable builds use `image_build` with a Dockerfile instead; publish the result with `image_tag` + `image_push`. The container is paused by default during the snapshot to ensure filesystem consistency - set `pause=False` only if the container cannot be paused. `changes` accepts Dockerfile instructions to apply on top of the snapshot, e.g. `["CMD ["python", "app.py"]", "ENV FOO=bar"]`. Args: id_or_name: Container id or name to snapshot repository: Repository name for the new image, e.g. "myorg/myimage" tag: Tag for the new image (default: "latest") message: Commit message stored in the image metadata author: Author string stored in the image metadata pause: Pause the container during commit for consistency changes: Dockerfile instructions (CMD, ENV, EXPOSE, etc.) to apply to the image conf: Additional image configuration overrides as a dict Returns: dict: The new image's full inspect payload (Id is the new image id)

Create a container from an image without starting it. Use this when you need to configure a container (with `extra_kwargs`) before its first start, or want creation and start as separate observable steps. For the common case of create-then-start-immediately use `container_run` instead - it does both in one call. Start the created container with `container_start`. Common `extra_kwargs` keys: `name` (str), `environment` (list of "KEY=VAL" or dict), `ports` (dict, e.g. `{"80/tcp": 8080}`), `volumes` (dict, e.g. `{"/host/path": {"bind": "/container/path", "mode": "rw"}}`), `labels` (dict). For anything else docker-py's `ContainerCollection.create` accepts, call `docs_lookup(section="containers")` rather than guessing a key name. Args: image: Image to create the container from, e.g. "nginx:alpine" command: Override the image's default command; string or list of strings extra_kwargs: Additional docker-py ContainerCollection.create keyword arguments Returns: dict: The created container's full inspect payload (not yet running)

List filesystem changes a container has made relative to its image. Use it to audit what a container wrote before `container_commit` or `container_archive_get`, or to debug unexpected writes. Only the writable container layer is compared - files in volumes and bind mounts never show up. Returns: list: Dicts of {"Path", "Kind"}; Kind 0=modified, 1=added, 2=deleted

Run a command inside a running container (for a compose service, prefer `compose_exec`). Security: when any element of `cmd` is agent-controlled, use an exec-form argv list that does not invoke a shell (e.g. `["python", "-V"]`, `["ls", path]`). A string `cmd`, or a shell form like `["sh", "-c", template]`, interprets shell metacharacters in the untrusted parts. Args: cmd: Command to execute (prefer exec-form argv, no shell, when any element is agent-controlled) tty: Allocate a pseudo-TTY privileged: Run with extended privileges user: User to run the command as detach: Detach from the exec environment: Environment variables, as `{"KEY": "value"}` or a list of "KEY=value" strings workdir: Working directory inside the container demux: Return stdout and stderr separately Returns: dict: {"exit_code", "output"}; output is combined stdout+stderr, or a [stdout, stderr] pair with demux=True

Export a container's filesystem as a tar archive: to a file on the server host, or in band. The tar is a flat filesystem snapshot with no image metadata or layers - use `image_save` for an archive that `image_load` can restore, and `container_archive_get` for a single file or directory. With `dest_path` the archive streams straight to disk (no byte cap), so it handles large containers - 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: dest_path: Destination path on the server host; omit to return the bytes in band overwrite: Replace dest_path if it already exists max_bytes: In-band mode: abort with ToolInputError beyond this many bytes (default 32 MiB) Returns: bytes | dict: the tar bytes (in band), or {"path": <resolved path>, "bytes_written": int}

Return the full inspect detail for a single container. Use this when you need complete information about one container - config, state, network settings, mounts, environment variables, and resource limits. To enumerate many containers use `container_list` instead (same payload per container by default; abridged with sparse=True). For just logs or stats use `container_logs` / `container_stats`. Args: id_or_name: Container id (full or short) or name Returns: dict: Full container inspect attrs (equivalent to `docker inspect`)

Send a signal to a running container (default SIGKILL - immediate, no graceful shutdown). Use it to force-kill a container that ignores `container_stop`, or with `signal` to poke a process without stopping it (e.g. SIGHUP for a config reload). For a normal shutdown prefer `container_stop`, which sends the container's configured stop signal first. Fails with a conflict error if the container is not running. When the server runs containerized it refuses to signal its own container. Args: signal: Signal name or number as a string (e.g. "SIGHUP", "9"); default SIGKILL Returns: dict: The container's full inspect payload after the signal

List containers on the daemon (running only by default). Pass all=True to include stopped containers. For a compose project `compose_ps` groups containers by service; for swarm services use `service_ps` (tasks may live on other nodes). Args: all: Show all containers, including stopped ones (default False: running only) since: Only show containers created after this id or name before: Only show containers created before this id or name limit: Maximum number of results filters: Filter by attributes (e.g. status, label) sparse: Skip inspect calls and return less detail ignore_removed: Ignore containers removed during listing; inert when `sparse=True`, which skips the inspect calls that would fail managed_only: Only return containers created by this MCP server (filters on the docker-mcp-server.managed label); combines with any `filters` given Returns: list: One dict per container: full inspect payloads by default (each match is inspected, like `container_inspect`); sparse=True skips the per-container inspect calls and returns the daemon's abridged list entries instead

Get the logs of a container: a one-shot snapshot by default, or a bounded live tail with `follow=True`. Follow mode returns when `limit_lines` lines are collected, `timeout_seconds` elapses, or the container exits, whichever comes first - so the agent can watch live output without blocking forever. `limit_lines`/`timeout_seconds` apply only in follow mode; `until` only in snapshot mode. Snapshot mode is capped at 32 MiB and raises ToolInputError past it, so a noisy container can't exhaust the server's memory; `service_logs` caps the same way and lets the caller raise it. Prefer an integer `tail`, or `since`, over `tail="all"` on a long-running container: "all" is safe but will abort on the cap rather than returning a partial answer, and a large result can still exceed the agent's context. Caveat for `ssh://` daemons: docker-py can't cancel an SSH stream, so in follow mode the `timeout_seconds` watchdog can't interrupt a fully silent container - use the snapshot mode there if you need a hard time bound. Args: tail: Number of lines from the end, or the literal "all" for everything since: Only return logs created after this unix timestamp until: Only return logs created before this unix timestamp (snapshot mode only) follow: Follow the live log stream instead of returning a snapshot limit_lines: Follow mode: max lines to collect before returning timeout_seconds: Follow mode: max wall-clock seconds before returning what was collected Returns: str: Decoded log output (up to `limit_lines` lines in follow mode). Raises ToolInputError in snapshot mode if the logs exceed 32 MiB.