Skip to main content
Glama
docker-mcp
by mpgharris

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:

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).

  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

Available Tools

17 tools
compose_actionA

Run a docker compose lifecycle action (up, down, pull, stop) against a compose project file. Uses the local Docker socket.

Inputs: action (required), projectFile (required), services, downVolumes, +1 more.

compose_queryA

Query docker compose state: "ps" (container status), "config" (resolved compose config), or "logs" (service log tail).

Inputs: action (required), projectFile (required), tail, services.

container_actionB

Start, stop, restart, pause, unpause, or remove a container.

Inputs: action (required), container (required), force, timeout.

container_createB

Create a new container from an image.

Inputs: image (required), env, name, ports, +1 more.

container_execA

Run a command in a running container. Output capped at 200 lines / 10KB.

Inputs: command (required), container (required), tty.

container_logsB

Get container logs. ANSI codes stripped, capped at max tail.

Inputs: container (required), tail, timestamps.

container_queryC

List or inspect Docker containers.

Inputs: action (required), limit, fields, fullId, +3 more.

docker_pingA

Check connectivity to the Docker daemon and return version/diagnostics.

Inputs: no named parameters.

image_actionB

Perform actions on Docker images: pull, remove, tag, or push.

Inputs: image (required), action (required), tag, auth, +2 more.

image_buildB

Build a Docker image from a context (tar file path) and optional Dockerfile.

Inputs: context (required), tag, buildargs, dockerfile.

image_queryA

Query Docker images: list all images or inspect a specific image by name or ID.

Inputs: action (required), image, limit, fields, +3 more.

network_actionC

Create, remove, connect, or disconnect a Docker network.

Inputs: action (required).

network_queryC

List or inspect Docker networks.

Inputs: action (required), limit, fields, network, +1 more.

system_dfA

Return Docker disk usage: breakdown by containers, images, volumes, and build cache. Output is already compact — shipped raw.

Inputs: no named parameters.

system_pruneA

Prune unused Docker resources by scope and return a summary of reclaimed space. Use scope "all" to prune every category and aggregate reclaimed bytes.

Inputs: scope (required).

volume_actionB

Create or remove a Docker volume.

Inputs: action (required), name, force, driver, +2 more.

volume_queryB

List or inspect Docker volumes.

Inputs: action (required), limit, fields, volume, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool targets a distinct resource (compose, container, image, network, system, volume) and action (action, query, create, etc.), with no overlaps. Even similar verbs like 'action' and 'query' are clearly separated by resource type.

    Naming Consistency5/5

    Tool names follow a consistent snake_case pattern: resource_action (e.g., container_create, image_build, network_query). The only exception is 'docker_ping', but it still follows the convention of prefixing with the resource name.

    Tool Count5/5

    17 tools is appropriate given Docker's broad domain, covering containers, images, networks, volumes, compose, and system operations. Each tool serves a distinct purpose without unnecessary bloat.

    Completeness4/5

    The tool set covers core CRUD and lifecycle operations for all major Docker resources, including compose. Minor gaps exist (e.g., container commit, stats, login), but the surface is sufficient for most common workflows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Allows Claude and other AI assistants to interact with Docker through the MCP protocol, enabling container and image management including listing, running, stopping, and pulling Docker resources.
      6
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables secure Docker command execution from isolated environments like containers through MCP protocol. Provides tools for managing Docker containers, images, and Docker Compose services with security validation and async operation support.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables remote Docker management over SSH via a local MCP server, providing tools to manage containers, images, Compose, and system resources.
      1
      GPL 3.0