DockerBro

DockerBro is a proper MCP-compliant Docker management server. Speaks JSON-RPC 2.0 over stdin/stdout and communicates with the Docker daemon via /var/run/docker.sock.

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

Features

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.

Setup

Option A: Run locally (recommended for Zed)

1. Install dependencies:

   pip3 install docker
   

2. Make sure Docker is running and /var/run/docker.sock is accessible.

3. Test it works:

   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | python3 docker_mcp_server.py
   

4. Add to Zed (see Zed Configuration below).

Option B: Run in Docker container

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

Zed Configuration

Add this to ~/.config/zed/settings.json inside the root object:

"context_servers": {
  "dockerbro": {
    "command": "python3",
    "args": ["/Users/YOUR_USERNAME/Desktop/docker-mcp-server/docker_mcp_server.py"],
    "env": {
      "DOCKER_MCP_LOG": "/tmp/docker-mcp-server.log"
    }
  }
}

Optionally, restrict tools server-side by adding env vars:

"env": {
  "DOCKER_MCP_LOG": "/tmp/docker-mcp-server.log",
  "DOCKER_MCP_DENY_TOOLS": "remove_container,remove_image,exec_container,docker_compose_down"
}

Replace YOUR_USERNAME with your macOS username.

Then reload Zed (cmd-shift-p > Reload Window). The agent will have 16 Docker tools available.

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "dockerbro": {
      "command": "python3",
      "args": ["/Users/YOUR_USERNAME/Desktop/docker-mcp-server/docker_mcp_server.py"],
      "env": {
        "DOCKER_MCP_LOG": "/tmp/docker-mcp-server.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"}}}' | python3 docker_mcp_server.py

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | python3 docker_mcp_server.py

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

Via MCP Inspector

npx @modelcontextprotocol/inspector python3 docker_mcp_server.py

Architecture

AI Editor (Zed/Claude/Cursor)
    |  (stdin/stdout: JSON-RPC 2.0)
    v
docker_mcp_server.py
    |  (Python docker SDK)
    v
/var/run/docker.sock
    |
    v
Docker Daemon

License

MIT