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"]
    }
  }
}

Related MCP server: MCP Docker Server

Configuration

Configure via environment variables, matching Docker CLI conventions:

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

Image tools

Volume tools

Network tools

Compose tools

System tools

Health

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