<div align="center">

<img src="https://raw.githubusercontent.com/falkenslab/docker-mcp/main/docs/static/img/logo.svg" alt="docker-mcp logo: two puzzle pieces fitting together, a robot for the agent and stacked containers for Docker" width="112"/>

# docker-mcp

**Your AI agent works Docker for you: containers, images, Compose and practice labs.**<br/>
A complete set of tools, with modes chosen at startup: only read, only safe labs, or everything.

[![npm](https://img.shields.io/npm/v/@falkenslab/docker-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/@falkenslab/docker-mcp)
![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white)
![Docker 24+](https://img.shields.io/badge/Docker-24%2B-1d63ed?logo=docker&logoColor=white)
![MCP server](https://img.shields.io/badge/MCP-server-0b0b0b)
[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](LICENSE)

**[📖 Documentation](https://falkenslab.github.io/docker-mcp/)** · [📖 Documentación en español](https://falkenslab.github.io/docker-mcp/es/)

</div>

docker-mcp is an MCP server that lets an AI agent (Claude Code, Codex, an agent built on [agent-kit](https://github.com/falkenslab/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](https://nodejs.org) 20 or later and [Docker](https://docs.docker.com/get-started/get-docker/) 24 or later, running.

```bash
# 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](https://falkenslab.github.io/docker-mcp/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](https://github.com/falkenslab/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

<p align="center">
<img src="https://raw.githubusercontent.com/falkenslab/docker-mcp/main/docs/static/img/see-it-claude-code.png" alt="Claude Code starting a lab with docker-mcp and its check passing" width="760"/>
</p>

<p align="center"><em>Claude Code, in lab mode: it starts a practice lab and its check passes, all through docker-mcp.</em></p>

<p align="center">
<img src="https://raw.githubusercontent.com/falkenslab/docker-mcp/main/docs/static/img/see-it-codex.png" alt="Codex starting a lab with docker-mcp and running its check" width="760"/>
</p>

<p align="center"><em>Codex, with the same lab: it calls list_labs, lab_up and lab_check, and the check passes.</em></p>

## 🧰 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](https://falkenslab.github.io/docker-mcp/reference/tools).

## 📚 Documentation

- **[Getting started](https://falkenslab.github.io/docker-mcp/getting-started)**: installing it in your AI app.
- **[Configuration](https://falkenslab.github.io/docker-mcp/configuration)**: `.mcp.json` for Claude Code and `config.toml` for Codex, or their command lines, with every setting.
- **[Modes and settings](https://falkenslab.github.io/docker-mcp/modes)**: `read`, `lab` and `full`, the areas, and the labs' policy.
- **[Tools](https://falkenslab.github.io/docker-mcp/reference/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.

<div align="center">

Made with 💖 by Falken's Lab Team

</div>