DockerBro

DockerBro is a proper MCP-compliant Docker management server. Speaks JSON-RPC 2.0 over stdin/stdout and talks to your local Docker daemon.

Works with Zed, Claude, Cursor, VS Code, and any other MCP-compatible AI editor.

Runs on macOS, Linux, and Windows.

pip install dockerbro

Features

Related MCP server: Docker MCP Server

Pre-approving tools

Each tool is annotated with MCP spec annotations (readOnlyHint, destructiveHint, idempotentHint) so spec-aware clients (Claude Code, Cursor, etc.) can auto-approve read-only tools without prompting.

You can also restrict tools at the server level via environment variables, enforced before anything reaches the client:

Example: only safe read-only tools

Pass the env var in your Zed config (add to the env object):

"env": {
  "DOCKER_MCP_ALLOW_TOOLS": "list_containers,inspect_container,logs_container,list_images,docker_compose_ps,docker_compose_logs"
}

If a tool is not pre-approved, the server returns an error:

Tool 'remove_container' is not pre-approved (blocked by server allow/deny config).

Note: Client-side approval (e.g. Zed's agent.tool_permissions) and server-side pre-approval are independent. The server-side list controls which tools are visible and callable at all; the client controls which of those require a confirmation prompt.

Requirements

• Python 3.9+

• Docker installed and running

Install

Option A: From PyPI (recommended — all platforms)

command not found: pip? On macOS and many Linux distros, Python 3 installs it as pip3. On Windows it's usually pip or py -m pip. When in doubt, python3 -m pip install dockerbro works everywhere.

This puts a dockerbro command on your PATH, so your editor config needs no file paths at all.

Verify it works:

dockerbro --version 2>/dev/null; echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | dockerbro

Option B: Run from source

git clone https://github.com/ramanailearning-cpu/dockerbro.git
cd dockerbro
pip install -e .

Option C: Run in a Docker container

Build it:

docker build -t dockerbro .

Run it — the socket mount differs per platform:

macOS / Linux:

docker run --rm -i -v /var/run/docker.sock:/var/run/docker.sock dockerbro

Windows (PowerShell):

docker run --rm -i -v //./pipe/docker_engine://./pipe/docker_engine dockerbro

Connecting to the Docker daemon

DockerBro auto-detects your daemon, so this usually needs zero configuration:

To point at a different or remote daemon, set DOCKER_HOST in your config's env block:

"env": { "DOCKER_HOST": "tcp://192.168.1.50:2375" }

macOS Docker Desktop note: if you get a connection error, enable Settings → Advanced → Allow the default Docker socket, or set DOCKER_HOST to unix:///Users/YOUR_NAME/.docker/run/docker.sock.

Zed Configuration

Add this to your Zed settings file (Cmd-Shift-P → Open Settings on macOS, Ctrl-Shift-P on Linux/Windows):

"context_servers": {
  "dockerbro": {
    "command": "dockerbro",
    "env": {
      "DOCKER_MCP_LOG": "/tmp/dockerbro.log"
    }
  }
}

Restricting tools server-side

Optionally, add env vars to limit which tools are exposed:

"env": {
  "DOCKER_MCP_LOG": "/tmp/dockerbro.log",
  "DOCKER_MCP_DENY_TOOLS": "remove_container,remove_image,exec_container,docker_compose_down"
}

Reload Zed (Cmd-Shift-P on macOS / Ctrl-Shift-P on Linux or Windows → Reload Window). The agent will have 16 Docker tools available.

Windows note: If the dockerbro command isn't found by Zed, use the full path shown by where dockerbro in your terminal.

Claude Desktop Configuration

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dockerbro": {
      "command": "dockerbro",
      "env": {
        "DOCKER_MCP_LOG": "/tmp/dockerbro.log"
      }
    }
  }
}

Linux

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dockerbro": {
      "command": "dockerbro",
      "env": {
        "DOCKER_MCP_LOG": "/tmp/dockerbro.log"
      }
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json (paste the path into Explorer's address bar):

{
  "mcpServers": {
    "dockerbro": {
      "command": "dockerbro",
      "env": {
        "DOCKER_MCP_LOG": "C:\\Users\\YOU\\dockerbro.log"
      }
    }
  }
}

Testing

Via terminal (pipe JSON-RPC)

# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | dockerbro

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | dockerbro

# Call a tool
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_containers","arguments":{"all":true}}}' | dockerbro

Via MCP Inspector

npx @modelcontextprotocol/inspector dockerbro

Architecture

AI Editor (Zed / Claude / Cursor / VS Code)
    |  (stdin/stdout: JSON-RPC 2.0)
    v
dockerbro  (Python)
    |  (Docker SDK)
    v
Docker Daemon

License

MIT