🐳 mcp-server-docker

A Model Context Protocol (MCP) server that lets AI assistants (Claude Code, Cursor, Claude Desktop) inspect and manage Docker environments, on one machine or on several.

Built with TypeScript and dockerode. It talks to the Docker Engine API directly (no docker CLI needed locally) over a local socket, TCP/TLS or SSH.

✨ Features

• Multi-host: drive several Docker daemons (your machine, a NAS, a server) from one server, each with a name.

• Safe by design: a global --read-only flag and a per-host readOnly option. Write tools are not even exposed when no host is writable, and every write is checked again in the service layer.

• Context-friendly: logs are demultiplexed and size-capped, docker_inspect returns a compact view, and every output is truncated with an explicit marker.

• Secrets masked: environment variables named like KEY, TOKEN, PASSWORD, SECRET, PASS or CREDENTIAL are replaced by ***REDACTED*** (disable with --no-redact).

• Short, actionable errors: no stack traces, and a failing host never breaks the others.

Related MCP server: Docker MCP Server

🛠 Tools

Write tools are hidden when every host is read-only. Container references are names or ids, never patterns.

🚀 Quick Start

Single host

Without a configuration file, the server uses DOCKER_HOST (or the local socket /var/run/docker.sock):

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "@zeearth/mcp-server-docker", "--read-only"]
    }
  }
}

Several hosts

Create a JSON file outside your repositories, for example ~/.config/mcp-server-docker/hosts.json:

{
  "defaultHost": "local",
  "hosts": {
    "local": { "url": "unix:///var/run/docker.sock" },
    "nas": {
      "url": "ssh://user@nas.lan:22",
      "readOnly": true,
      "dockerCommand": "/usr/local/bin/docker",
      "identityFile": "~/.ssh/nas-key"
    }
  }
}

Then point the server at it with --config (or the MCP_DOCKER_CONFIG environment variable):

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "@zeearth/mcp-server-docker", "--config", "/home/me/.config/mcp-server-docker/hosts.json"]
    }
  }
}

With Claude Code: claude mcp add docker -- npx -y @zeearth/mcp-server-docker --config <path>.

Host options

How the host parameter works

Every tool takes a host parameter restricted to the configured names.

• With a single host it is optional.

• With several hosts, read tools use defaultHost when it is set.

• Write tools always need an explicit host when several are configured, so an action never lands on the wrong machine by omission.

SSH hosts

The SSH transport opens a connection, runs <dockerCommand> system dial-stdio on the remote machine and tunnels the Docker API through it.

• Port: put it in the URL (ssh://user@host:2345). Your ~/.ssh/config is not read.

• Authentication: ssh-agent (SSH_AUTH_SOCK) and/or identityFile.

• Host key: checked strictly against ~/.ssh/known_hosts. Connect once with the ssh command to record a new host; a changed key is refused.

• Remote docker: the user must be allowed to run docker (e.g. docker group). Non-interactive SSH sessions often lack docker in PATH (Synology: /usr/local/bin/docker), hence dockerCommand.

🏗 Development

Everything runs in Docker, so nothing is installed on the host:

cp .env.example .env            # fill HOST_UID / HOST_GID
docker compose run --rm --no-deps node npm install
docker compose run --rm --no-deps node npm test
docker compose run --rm --no-deps node npm run typecheck
docker compose run --rm --no-deps node npm run build

See docs/ARCHITECTURE.md for the design and docs/ROADMAP.md for the implementation plan.

🛡️ Security Considerations

Giving an AI agent access to a Docker daemon is equivalent to giving it root-level control of that machine.

1. Prefer --read-only, or readOnly: true on every host where lifecycle management is not needed.

2. Keep the configuration file and SSH keys outside the repository, readable only by you.

3. For SSH hosts, use a dedicated account with only the permissions it needs.

4. Redaction only looks at environment variable names; review what docker_inspect full mode returns before sharing it.

📄 License

MIT