docker-mcp

MCP (Model Context Protocol) server wrapping the Docker Engine API. Exposes Docker operations as typed MCP tools, reducing token consumption versus generating CLI commands.

Quick Start

npx docker-mcp

Or add to your MCP client config (OpenCode, Claude Desktop, etc.):

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["docker-mcp"]
    }
  }
}

Configuration

Configure via environment variables, matching Docker CLI conventions:

Variable	Purpose	Example
DOCKER_HOST	Docker daemon address	ssh://user@192.168.1.111
DOCKER_TLS_VERIFY	Enable TLS	1
DOCKER_CERT_PATH	TLS cert directory	~/.docker/certs

Default: Connects to local Docker socket (/var/run/docker.sock).

Connection methods (recommended order)

1. SSH (preferred): DOCKER_HOST=ssh://user@host — dockerode handles SSH natively. Pre-populate ~/.ssh/known_hosts to avoid host key prompts.
2. TCP + TLS: DOCKER_HOST=tcp://host:2376 with DOCKER_TLS_VERIFY=1 and DOCKER_CERT_PATH.
3. Plain TCP: DOCKER_HOST=tcp://host:2375 — warning: unencrypted TCP grants root access to anyone on the network. Only use on trusted LANs.

Authentication

For private registries, prefer pre-configuring credentials:

docker login myregistry.io

dockerode reads ~/.docker/config.json automatically. Inline auth parameters are also supported on image_action pull/push, but note that credentials transit the MCP protocol (stdin/stdout).

Tools (17 total)

Container tools

Tool	Description
container_query	List or inspect containers. Supports filters (status, label), limit, field selection, verbose mode.
container_action	Start, stop, restart, pause, unpause, or remove containers.
container_create	Create a container from an image with env, ports, volumes.
container_logs	Get container logs with tail limit (default 100, max 10,000) and timestamps. ANSI codes stripped.
container_exec	Run a command inside a running container. Output capped at 10KB/200 lines.

Image tools

Tool	Description
image_query	List or inspect images. Supports dangling filter, field selection.
image_action	Pull, remove, tag, or push images. Supports registry auth.
image_build	Build an image from a Dockerfile.

Volume tools

Tool	Description
volume_query	List or inspect volumes.
volume_action	Create or remove volumes.

Network tools

Tool	Description
network_query	List or inspect networks.
network_action	Create, remove, connect, or disconnect networks.

Compose tools

Tool	Description
compose_action	Up, down, pull, or stop Compose projects. Fire-and-forget for up (check with compose_query ps).
compose_query	List services (ps), validate config, or get logs.

System tools

Tool	Description
system_df	Docker disk usage breakdown.
system_prune	Prune unused resources by scope (all, containers, images, volumes, networks, builder).

Health

Tool	Description
docker_ping	Check Docker daemon connectivity and return version info.

Token Optimization

This server is designed to minimize token consumption:

• Default summaries: Query tools return curated fields by default. Use verbose: true for full payloads.
• Field selection: Pass fields: ["Id", "State.Status"] to get only the data you need.
• Pagination: Use limit on list tools to cap result size.
• Log capping: Logs default to 100 lines (max 10,000). Exec output capped at 10KB/200 lines.
• Compact IDs: 12-character IDs by default. Use fullId: true for full 64-char IDs.
• ANSI stripping: All output has ANSI codes stripped server-side.
• Tool consolidation: Related operations merged into 17 tools via action enums instead of 35 individual tools.

Security Notes

• container_exec allows arbitrary command execution in any container — equivalent to docker exec.
• image_build accepts a context path — ensure it points to a project directory, not / or /etc.
• Inline auth credentials on image_action transit the MCP protocol (stdio). Prefer docker login.
• Plain TCP Docker sockets grant root access without authentication. Use SSH or TLS when accessing remote hosts.

Development

# Install
npm install

# Dev server with hot reload
npm run dev

# Build
npm run build

# Test
npm test                 # Unit tests (no Docker needed)
npm run test:integration # Integration tests (requires Docker)
npm run lint             # Lint
npm run typecheck        # TypeScript check

# Format
npm run format

Architecture

src/
  index.ts         — Entrypoint, DI wiring, stdio transport
  config.ts        — Docker client factory (reads DOCKER_HOST env vars)
  error.ts         — Centralized error handler with status-code mapper
  utils/
    compose.ts     — Compose arg builder + JSON output parser (pure)
    summarize.ts   — Token optimization utilities (field projection, ID truncation, ANSI stripping, output capping)
  tools/
    types.ts       — Shared types + tool registration helpers
    health.ts      — docker_ping (validates pipeline)
    containers.ts  — 5 container tools
    images.ts      — 3 image tools
    volumes.ts     — 2 volume tools
    networks.ts    — 2 network tools
    compose.ts     — 2 compose tools
    system.ts      — 2 system tools

License

MIT