Metadata-Version: 2.4
Name: dockerbro
Version: 1.0.0
Summary: DockerBro — a proper MCP-compliant Docker management server for AI editors (Zed, Claude, Cursor, VS Code).
Author: Ramanpreet Singh
License: MIT
Keywords: docker,mcp,model-context-protocol,containers,ai-editor
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: docker>=7.0.0
Dynamic: license-file

# 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

| Tool | What it does | Safety |
|---|---|---|
| `list_containers` | List all containers with status, image, ports | Read-only |
| `inspect_container` | Detailed container info (network, mounts, env) | Read-only |
| `start_container` | Start a stopped container | Reversible |
| `stop_container` | Stop a running container | Reversible |
| `restart_container` | Restart a container | Reversible |
| `remove_container` | Remove a container (with optional force) | ⚠️  Destructive |
| `logs_container` | Get recent log output | Read-only |
| `exec_container` | Run a command inside a running container | ⚠️  Destructive |
| `list_images` | List local Docker images | Read-only |
| `pull_image` | Pull an image from a registry | Reversible |
| `run_container` | Run a new container with ports, env, etc. | Reversible |
| `remove_image` | Remove a local image | ⚠️  Destructive |
| `docker_compose_ps` | List Compose services | Read-only |
| `docker_compose_up` | Start Compose services | Reversible |
| `docker_compose_down` | Stop and remove Compose services | ⚠️  Destructive |
| `docker_compose_logs` | Get Compose service logs | Read-only |

---

## Pre-approving tools

Each tool is annotated with [MCP spec annotations](https://modelcontextprotocol.io/specification/2025-03-26/server/utilities/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:

| Env var | Effect |
|---|---|
| `DOCKER_MCP_ALLOW_TOOLS` | Comma-separated allowlist — only these tools are exposed and callable |
| `DOCKER_MCP_DENY_TOOLS` | Comma-separated denylist — always blocked (deny wins over allow) |

### Example: only safe read-only tools

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

```json
"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:**
   ```bash
   pip3 install docker
   ```

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

3. **Test it works:**
   ```bash
   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](#zed-configuration) below).

### Option B: Run in Docker container

```bash
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:

```json
"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:

```json
"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`:

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

```bash
# 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

```bash
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
