docker-mcp-server

# Docker MCP Server — Docker tools for AI agents

**A Docker MCP server that lets AI agents operate Compose stacks with structured,
Docker-native tools — instead of brittle shell commands and terminal-shaped output.**

Inspect containers, read logs, check health, query databases, take dumps, and bring stacks up or
down — on your laptop or on a server across the world by naming its profile.

It speaks Docker the way you do: your compose files, project names, and service names. Answers
come back as named fields with enough context for an agent to act on them, rather than parse an
ASCII table and guess.

Works with Claude Code, Codex CLI, Cursor, opencode, Gemini CLI, Qwen Code and other MCP clients.

[![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0%2Fservers%3Fsearch%3Dio.github.hypnosis%2Fdocker-mcp-server%26version%3Dlatest&query=%24.servers%5B0%5D.server.version&style=flat-square&logo=modelcontextprotocol&logoColor=white&label=MCP%20Registry&color=0F172A)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.hypnosis/docker-mcp-server&version=latest) [![npm version](https://img.shields.io/npm/v/@hypnosis/docker-mcp-server?style=flat-square&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@hypnosis/docker-mcp-server) [![npm downloads](https://img.shields.io/npm/dm/@hypnosis/docker-mcp-server?style=flat-square&logo=npm&logoColor=white&color=2EA043&label=downloads)](https://www.npmjs.com/package/@hypnosis/docker-mcp-server) [![tests](https://img.shields.io/github/actions/workflow/status/hypnosis/docker-mcp-server/test.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=tests)](https://github.com/hypnosis/docker-mcp-server/actions/workflows/test.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](LICENSE)

**[Install](#install-in-30-seconds) · [Tools](#docker-mcp-tools-for-containers-compose-and-databases) · [Setup](#set-up-the-docker-mcp-server) · [Security](#destructive-command-protection-for-ai-agents) · [Docs](docs/tools.md) · [Changelog](CHANGELOG.md)**

---

## Install in 30 seconds

No global installation required. `npx` downloads the package on first use:

```bash
npx -y @hypnosis/docker-mcp-server
```

Add it to your MCP client — **Claude Code**, for example — for every project:

```bash
claude mcp add docker -s user -- npx -y @hypnosis/docker-mcp-server
```

That is the whole setup for the Docker on this machine. No profiles file, no environment
variables: the server uses the local Docker socket, and the compose project of your working
directory is the project it answers about.

For a Docker host on another machine, add one file with the servers you reach over SSH:

```bash
claude mcp add docker -s user \
  -e DOCKER_MCP_PROFILES_FILE="$HOME/.claude/docker-profiles.json" \
  -- npx -y @hypnosis/docker-mcp-server
```

```json
{
  "default": "local",
  "profiles": {
    "local": { "mode": "local" },
    "production": {
      "host": "prod.example.com",
      "username": "deployer",
      "privateKeyPath": "~/.ssh/id_ed25519"
    }
  }
}
```

Now every tool takes a `profile`, and `docker_health({ action: "profiles" })` lists what the
server was given.

Codex, Cursor, opencode and other clients are covered in
[Set up the Docker MCP server](#set-up-the-docker-mcp-server).

### Install as a plugin

Some clients — **Claude Code**, for example — can take the whole thing as a plugin instead:

```
/plugin marketplace add hypnosis/docker-mcp-server
/plugin install docker-mcp-server@docker-mcp-server
```

The plugin brings the server up against the Docker on this machine, with no configuration at
all. Point it at other hosts the same way as above, with `DOCKER_MCP_PROFILES_FILE`.

### Requirements

[![Node.js](https://img.shields.io/node/v/@hypnosis/docker-mcp-server?style=flat-square&logo=nodedotjs&logoColor=white&color=5FA04E)](https://nodejs.org/) [![TypeScript](https://img.shields.io/npm/dependency-version/@hypnosis/docker-mcp-server/dev/typescript?style=flat-square&logo=typescript&logoColor=white&color=3178C6&label=typescript)](https://www.typescriptlang.org/) [![MCP SDK](https://img.shields.io/npm/dependency-version/@hypnosis/docker-mcp-server/@modelcontextprotocol/sdk?style=flat-square&logo=modelcontextprotocol&logoColor=white&color=0F172A&label=MCP%20SDK)](https://modelcontextprotocol.io/)

**Node.js 18+** and a Docker daemon you can already reach — the local socket, or a remote host
over SSH with a key.

The server starts whether or not Docker is up. A call made while the daemon is down answers
"start Docker" and works on the next try, without restarting your MCP client.

Prefer a pinned version, offline work, or one less registry check per launch:
`npm install -g @hypnosis/docker-mcp-server`, then use `docker-mcp-server` as the command
instead of `npx`.

## Who this Docker MCP server is for

- **AI-assisted developers** who build, run, and debug applications with Docker Compose.
- **Backend and full-stack developers** who need their coding agent to inspect containers, logs,
  health checks, databases, and Compose services while solving a problem.
- **Independent developers and small product teams** who deploy Docker applications to their own
  servers and want one agent workflow for local development and production.
- **Platform engineers** who maintain Docker environments across development, staging, and
  production hosts.
- **DevOps engineers and SREs using AI coding agents** for incident checks, routine container
  work, and faster investigation of Compose-based services.
- **Agencies and technical teams maintaining client applications**, where an agent needs to
  understand an unfamiliar Compose stack before making a change.
- **QA and release engineers** who need repeatable visibility into test stacks, service health,
  logs, and databases before a release.

## Why use a Docker MCP server instead of raw Docker CLI?

Docker CLI is excellent for a person at a terminal. An AI agent needs something different: Docker
and Compose concepts it can query directly, results it can reason about, and clear boundaries
between what happened, what was not found, and what could not be checked.

### Less context, lower AI cost

`docker ps`, `docker stats`, and `docker logs` are designed to be read on a screen. Their output
mixes labels, values, units, and formatting into text an agent must parse before it can use it.

A Docker MCP tool returns the fields the task needs: service, project, state, health, ports,
timestamps, byte counts, exit codes, and log streams. The agent receives less terminal noise,
spends fewer tokens interpreting it, and keeps more context for the problem it is solving.

### Debug Docker Compose as a system

A Docker application is more than a list of containers. It is a Compose project with services,
dependencies, health checks, logs, databases, and resources that affect one another.

The server lets an agent ask about that system in the names you use every day: the project,
service, and Compose file. One call can show the state and health of a stack; another can inspect
a bounded log window, measure a service, or query the database already running beside it. The
agent spends its turns finding the cause, not assembling and decoding shell commands.

### Make decisions from explicit results

A shell command can return an empty table, clipped output, or an error printed alongside ordinary
text. For an agent, those are different situations — and treating them as the same leads to
guesses.

Docker MCP results say what was found, what was not found, what was cut short, and why an action
did not run. A missing healthcheck is not a failed healthcheck; an empty list is not a failed
read; a command with no exit code never started. That gives the agent a reliable basis for its
next step, and gives you fewer confident-looking but wrong fixes.

## Manage local and remote Docker hosts over SSH

Use the same Docker MCP tools on the Docker daemon beside you and on a remote server. A remote
Docker host is a profile: a stable name, its SSH connection, and the authentication it needs.
The agent names that profile in a tool call:

```typescript
docker_container({ "action": "list", "profile": "production" })
```

Leave `profile` out and the default Docker host answers, so local development stays frictionless.
Name a profile the server does not know and the response lists the profiles it does know instead
of quietly sending a request to another machine.

Remote Docker Compose projects are resolved by the labels their containers already carry. Ask for
a project by name wherever it lives on that host — no remote working directory or fixed Compose
path to maintain. For a project that has not run there yet, pass its file explicitly with
`compose_path`.

## Built for the Model Context Protocol

A native Docker MCP server built on the official MCP SDK, with structured tools designed for
AI agents rather than terminal automation.

Its behaviour is covered by unit tests and end-to-end tests that run against real Docker
containers, not only mocks.

---

## Docker MCP vs Docker CLI: practical examples

The Docker CLI is the right interface when a person is driving the terminal. These examples show
what changes when an AI agent needs to inspect a Docker Compose application, understand the
result, and choose the next safe step.

Each comparison uses the same real-world task: first the commands and output an agent would have
to work through, then the structured Docker MCP result it can use directly.

### Diagnose the health of a Docker Compose stack

> **Situation:** A deploy just went out. The site is slow, and you do not know whether a
> container is down, a healthcheck is failing, or something is eating the memory.
>
> **Question:** "Is this stack healthy?"

#### Raw docker CLI

```console
$ docker compose ps
NAME              IMAGE               STATUS