docker-mcp

Overview Schema Source Related Servers Discussions Admin

Run a container

run_container

Create and start a Docker container from an image, pulling it if missing. It runs in the background by default and blocks risky options unless you confirm them.

Instructions

Create and start a container from an image (pulled if missing), in the background unless detach is false. Dangerous options (privileged, the host's network, processes or IPC, extra capabilities, devices, mounting the Docker socket, the host's root or the person's home) are refused unless confirmedDangerous is true: ask the person first, naming what they give the container. Changes the machine: confirm with the person first.

Input Schema

TableJSON Schema

Name	Required	Description
`env`	No	Environment variables
`ipc`	No
`pid`	No
`name`	No
`image`	Yes	The image, e.g. nginx:1.27 or postgres:17
`ports`	No	Published ports, "host:container", e.g. "8080:80"; "127.0.0.1:8080:80" to keep them on this computer
`capAdd`	No
`detach`	No	In the background (default); false waits for it to finish and returns its output
`remove`	No	Remove it when it stops
`command`	No	The command and its arguments, one per item; the image's when missing
`devices`	No
`network`	No	A network to join
`restart`	No
`volumes`	No	Mounts, "named-volume:/path" or "/host/path:/path[:ro]"
`workdir`	No
`privileged`	No
`confirmedDangerous`	No	The person confirmed the dangerous options, knowing what they give the container

Output Schema

TableJSON Schema

Name	Required	Description
`output`	Yes
`exitCode`	Yes
`container`	Yes	Its id (detached)
`truncated`	Yes	The start was left out: it was longer than a model's context fits

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 18, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: discloses that the image is pulled if missing, that it runs detached by default, that dangerous options are refused unless confirmedDangerous is true, and that the person must be asked first. This is rich behavioral context that the readOnly/destructive/idempotent hints do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then the safety model, then a short reminder. The parenthetical dangerous-options list is long but each item carries real meaning, so it is dense rather than wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 17-parameter tool with an output schema, the description covers the essentials an agent needs: default detach behavior, image pull, and the confirmation gate. Remaining param gaps (name, restart, workdir) are minor and largely covered by the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

At 53% schema coverage the description must compensate, and it does for the safety-critical subset: privileged, host network, pid/ipc, capAdd, devices, and volumes (Docker socket, host root, home) are tied to the confirmedDangerous gate, and detach is explained. It leaves name, restart, workdir, and env to the schema, so it is not complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource: "Create and start a container from an image (pulled if missing)." This distinguishes it from sibling start_container (start only) and exec_in_container, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational context: run in background unless detach is false, and requires human confirmation before dangerous options or machine changes. It does not explicitly name alternatives (e.g. start_container for an existing container), so it stops short of full when-not/alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.