docker-mcp
Your AI agent works Docker for you: containers, images, Compose and practice labs.
A complete set of tools, with modes chosen at startup: only read, only safe labs, or everything.
📖 Documentation · 📖 Documentación en español
docker-mcp is an MCP server that lets an AI agent (Claude Code, Codex, an agent built on agent-kit) work the Docker on your computer: run and inspect containers, build and pull images, manage volumes and networks, start Compose projects, clean up, and run practice labs that check themselves. You choose how far it can go when it starts: read only looks, lab only runs labs under a safety policy, and full does everything Docker does, asking before anything dangerous. It drives Docker's own command line, so it works wherever Docker does.
✨ Why docker-mcp
- 🎚️ Modes, not trust. A tool outside the mode doesn't exist for the agent: in
read it can't change anything, in lab it can't run anything but labs.
- 🛡️ You confirm, not the agent. Before removing anything, and before a privileged container, the host's network or the Docker socket, docker-mcp asks you itself through your app, and your answer never passes through the model.
- 🧪 Labs for practices. A folder with a
compose.yaml and a check: no internet, no host mounts, limits on CPU and memory, refused if it breaks the rules, reset in one call.
- 🧰 The whole of Docker. 47 tools over containers, images, volumes, networks, Compose and the system, each with structured results.
- 🔧 Explains, never installs. Without Docker, or with it stopped, it says how to install or start it.
- 📦 Nothing to install. One bundled file run with
npx, for agent-kit, Claude Code and Codex alike.
🚀 Quick start
You need Node.js 20 or later and Docker 24 or later, running.
# Claude Code (full mode)
claude mcp add docker -- npx -y @falkenslab/docker-mcp
# Only labs, with the practices in a folder of your own
claude mcp add docker -e DOCKER_MCP_MODE=lab -e DOCKER_MCP_LABS_DIR=/path/to/labs -- npx -y @falkenslab/docker-mcp
In Codex, codex mcp add docker -- npx -y @falkenslab/docker-mcp. To write it in .mcp.json or Codex's config.toml, with every setting, see Configuration. In an agent built on agent-kit, or with its skills in Claude Code and Codex, install the docker-lab extension from agent-extensions, which runs this server at a fixed version. Then ask: "What containers are running?"
💬 What you can ask
- 🧑💻 "Start a PostgreSQL 17 with a volume for its data, on port 5432 only for this computer."
- 🧑💻 "Why does my web container keep restarting? Look at its logs."
- 🧑💻 "How much disk is Docker using, and what could I clean up?"
- 👩🏫 "Start the volumes lab and check the solution works."
- 🧑🎓 "Reset my lab: I broke the database."
📸 See it at work
🧰 What's inside
| Area | Tools |
|---|
| 📦 Containers | list_containers, inspect_container, container_logs, container_stats, container_processes, run_container, start_container, stop_container, restart_container, remove_container, exec_in_container, copy_to_container, copy_from_container |
| 🖼️ Images | list_images, inspect_image, pull_image, build_image, tag_image, push_image, remove_image |
| 💾 Volumes and networks | list_volumes, inspect_volume, create_volume, remove_volume, and the same for networks |
| 🧩 Compose | compose_ps, compose_logs, compose_build, compose_up, compose_down, compose_exec |
| ⚙️ System | docker_info, disk_usage, prune |
| 🧪 Labs | list_labs, lab_status, lab_logs, lab_up, lab_exec, lab_check, lab_reset, lab_down |
| 🔌 Server | server_info, check_requirements |
Every tool, with what each mode keeps: the tools reference.
📚 Documentation
- Getting started: installing it in your AI app.
- Configuration:
.mcp.json for Claude Code and config.toml for Codex, or their command lines, with every setting.
- Modes and settings:
read, lab and full, the areas, and the labs' policy.
- Tools: every tool, generated from the server.
🛠️ Developing
npm install, then npm run build, npm test and npm run check before every commit; CLAUDE.md lists every command and .minispec/ the decisions behind them (the modes are ADR-005, the labs' policy ADR-006). Releases are published to npm by the owner.
Made with 💖 by Falken's Lab Team
