Mcpdockery

mcpdockery

An MCP server that gives an LLM (Claude, etc.) direct, natural-language control over your local Docker daemon — containers, images, volumes, networks, and Compose stacks.

Built with FastMCP and the Docker SDK for Python.

Table of contents

• Requirements
• Installation
• Running the server
• Connecting to an MCP client
• Available tools
• Usage examples
• Project structure
• Safety notes
• License

Requirements

For pulling from or pushing to a private registry (Docker Hub, AWS ECR, GCR, etc.), authenticate with that registry beforehand using your normal docker login flow — this server never accepts or stores credentials itself.

Installation

1. Clone the repository:

   git clone <this-repo>
   cd mcpdockery
   

2. Install dependencies:

   uv sync
   

   This creates a .venv and installs the exact dependency versions pinned in uv.lock.
3. Confirm Docker is running:

   docker info
   

   If this command fails, start Docker Desktop (or your Docker Engine) before continuing.

Running the server

uv run src/main.py

The server communicates over stdio, so it's meant to be launched by an MCP client rather than run standalone in a terminal.

Connecting to an MCP client

Add an entry to your MCP client's configuration (e.g. claude_desktop_config.json for Claude Desktop, or your project's .mcp.json for Claude Code):

{
  "mcpServers": {
    "mcpdockery": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcpdockery", "run", "src/main.py"]
    }
  }
}

Replace /absolute/path/to/mcpdockery with the actual path where you cloned the repository, then restart the client. The tools listed below will become available to the model.

Available tools

Containers (containers.py)

Images (images.py)

Volumes (volumes.py)

Networks (networks.py)

Optimization (optimization.py)

Diagnostics (diagnostics.py)

Security (security.py)

Compose stacks (stacks.py)

Usage examples

Once connected, you can drive the server with natural-language requests. A few examples of what to expect:

The model chooses which tool(s) to call based on your request — you don't need to name the tool yourself.

Project structure

src/
  main.py             # Entrypoint: registers tool modules and starts the MCP server
  server.py           # Shared FastMCP server instance
  docker_client.py    # Lazy singleton Docker SDK client
  compose_client.py   # Thin wrapper around the `docker compose` CLI
  helper.py           # Shared helpers (path normalization, image tag parsing, Trivy wrapper)
  containers.py       # Container lifecycle & inspection tools
  images.py           # Image pull/build/push/list/delete tools
  volumes.py          # Volume tools
  networks.py         # Network tools
  stacks.py           # Compose stack tools
  security.py         # Image/Dockerfile vulnerability & misconfiguration scanning tools
  diagnostics.py      # Cross-container health triage tools
  optimization.py     # Dockerfile efficiency analysis tools

Safety notes

This server gives the model real, unsandboxed control over your Docker daemon:

• delete_container, delete_image, remove_volume, and remove_stack are destructive and require an explicit confirm=True argument. The first call (confirm defaults to False) performs no action and only returns a preview of what would be deleted — the model is instructed to only pass confirm=True after you've explicitly agreed in the conversation. This is a safety net against a misread request, not a hard permission system: any client with tool access can still pass confirm=True directly.
• remove_stack deletes volumes (-v), which is destructive and irreversible for stateful data.
• container_exec runs arbitrary shell commands inside a container.
• container_logs, container_exec, and container_inspect redact values that look like secrets (keys matching PASSWORD/TOKEN/API_KEY/etc., in KEY=value, KEY: value, or "key": "value" form) before returning them. This is a best-effort heuristic, not a guarantee — anything that doesn't match the pattern (or that a container prints in an unusual format) is returned as-is, and remember that tool output is sent to the model provider as part of the conversation regardless of how "local" the Docker daemon is.
• push_image and pull_image use your existing local Docker credentials — the model can push to or pull from any registry you're currently authenticated with. Note that AWS ECR tokens expire after 12 hours; if a push/pull suddenly fails with an auth error, re-run your docker login / aws ecr get-login-password flow rather than assuming the tool is broken.
• The Docker socket grants root-equivalent access to the host. Giving a model tool access to this server is equivalent to giving it that level of access to your machine, whether or not the daemon is reachable over the network.

Only connect this server to clients/agents you trust, and be deliberate about which containers and stacks you let it touch.

License

No license specified.