Metadata-Version: 2.4
Name: docker-mcp-server
Version: 0.1.0
Summary: Docker MCP server exposing Docker operations as MCP tools
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: docker (>=7.0,<8.0)
Requires-Dist: mcp (>=1.12,<2.0)
Description-Content-Type: text/markdown

# Docker MCP Server

A Model Context Protocol (MCP) server that exposes Docker operations as tools — manage containers, images, compose services, volumes, and networks directly from Claude.

## Installation

```bash
pip install docker-mcp
```

Or with `uvx` (no install needed):

```bash
uvx docker-mcp
```

## MCP Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "docker": {
      "command": "uvx",
      "args": ["docker-mcp"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add docker -- uvx docker-mcp
```

Or add manually to your project's `.claude/settings.json`:

```json
{
  "mcpServers": {
    "docker": {
      "command": "uvx",
      "args": ["docker-mcp"]
    }
  }
}
```

### Docker (SSE mode)

Run the server as a container and connect over HTTP:

```bash
docker run -d \
  -p 8000:8000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/firasmosbahi/docker-mcp:latest
```

Then configure your MCP client to connect to `http://localhost:8000/sse`.

## Available Tools

### Containers

| Tool | Description |
|------|-------------|
| `list_containers` | List containers (`all=true` includes stopped) |
| `create_container` | Create a container without starting it |
| `run_container` | Create and start a container in one step |
| `start_container` | Start a stopped container |
| `stop_container` | Stop a running container |
| `restart_container` | Restart a container |
| `remove_container` | Remove a container (`force=true` for running) |
| `get_container_logs` | Get container logs (configurable tail lines) |
| `exec_in_container` | Execute a command inside a running container |
| `inspect_container` | Get full container details as JSON |
| `container_stats` | Get CPU and memory usage for a container |

**Examples:**

```
List all containers including stopped ones
→ list_containers(all=true)

Run an nginx container on port 8080
→ run_container(image="nginx", name="my-nginx", ports={"80/tcp": 8080}, detach=true)

Get the last 50 lines of logs from my-app
→ get_container_logs(container_id="my-app", tail=50)

Execute a command inside a container
→ exec_in_container(container_id="my-app", command="env")
```

### Images

| Tool | Description |
|------|-------------|
| `list_images` | List all local images with size |
| `pull_image` | Pull an image from a registry |
| `build_image` | Build an image from a Dockerfile |
| `tag_image` | Tag an image with a new name |
| `remove_image` | Remove an image |
| `inspect_image` | Get full image details as JSON |

**Examples:**

```
Pull the latest Alpine image
→ pull_image(image="alpine", tag="latest")

Build an image from the current directory
→ build_image(path="/my/project", tag="my-app:v1")

Tag an image for pushing to a registry
→ tag_image(image="my-app:v1", repository="myrepo/my-app", tag="v1.0.0")
```

### Compose

| Tool | Description |
|------|-------------|
| `compose_up` | Start services (detached by default) |
| `compose_down` | Stop and remove services |
| `compose_build` | Build or rebuild services |
| `compose_restart` | Restart services |
| `compose_ps` | List service status |
| `compose_logs` | Get service logs |

**Examples:**

```
Start all services in a project
→ compose_up(project_directory="/my/project")

Rebuild a specific service without cache
→ compose_build(project_directory="/my/project", service="api", no_cache=true)

Get logs for the web service
→ compose_logs(project_directory="/my/project", service="web", tail=100)
```

### Volumes

| Tool | Description |
|------|-------------|
| `list_volumes` | List all volumes |
| `create_volume` | Create a named volume |
| `remove_volume` | Remove a volume |
| `inspect_volume` | Get volume details |

### Networks

| Tool | Description |
|------|-------------|
| `list_networks` | List all networks |
| `create_network` | Create a network |
| `remove_network` | Remove a network |
| `inspect_network` | Get network details |
| `connect_container_to_network` | Connect a container to a network |
| `disconnect_container_from_network` | Disconnect a container from a network |

### System

| Tool | Description |
|------|-------------|
| `system_info` | Docker version, OS, container/image counts, disk usage |
| `prune_containers` | Remove all stopped containers |
| `prune_images` | Remove unused (dangling) images |
| `prune_volumes` | Remove unused volumes |
| `prune_networks` | Remove unused networks |

**Examples:**

```
Check Docker system status and disk usage
→ system_info()

Free up space by removing unused resources
→ prune_containers()
→ prune_images()
→ prune_volumes()
```

## Transport Modes

```bash
# stdio (default) — for MCP clients that manage the process
docker-mcp

# SSE — for HTTP-based MCP clients
docker-mcp --transport sse --port 8000
```

## Requirements

- Python 3.11+
- Docker daemon running and accessible (Docker Desktop or Docker Engine)

## Development

```bash
git clone https://github.com/firasmosbahi/docker-mcp
cd docker-mcp
poetry install
poetry run pytest
```

