# Docker Container Manager MCP Server

> An MCP server that gives any LLM client the ability to list, inspect, start, stop, and monitor Docker containers on the host machine — putting your entire container stack at your AI assistant's fingertips.

---

## Overview

This server wraps the [Docker SDK for Python](https://docker-py.readthedocs.io/en/stable/) using [FastMCP](https://gofastmcp.com), exposing container management operations as tools any MCP-compatible client can call. Connect it to Claude Desktop and you can ask Claude to check container health, fetch logs, inspect configuration, or monitor live CPU and memory usage — all from a single conversation.

The server connects to the Docker daemon via the Unix socket on startup, verifies connectivity with a ping, and shares the client across all tool calls via FastMCP's lifespan context. No tokens required — just a running Docker daemon.

---

## Tools

| Tool | Description |
|---|---|
| `list_containers` | List running or all containers with status and port mappings |
| `start_container` | Start a stopped container by name or ID |
| `stop_container` | Stop a running container gracefully |
| `get_container_logs` | Fetch the last N lines of timestamped logs |
| `inspect_container` | Get full container details — image, env vars, mounts, network |
| `get_container_stats` | Get live CPU and memory usage matching `docker stats` output |

---

## Project Structure

```
docker-manager-mcp/
├── server.py          # FastMCP instance, lifespan, tool registration
├── config.py          # Environment variables and constants
├── tools/
│   ├── __init__.py
│   ├── containers.py  # list, start, stop, logs, inspect
│   └── stats.py       # get_container_stats with accurate CPU/memory calculation
├── .env               # Optional overrides
├── .env.example       # Template
├── requirements.txt
├── Dockerfile
└── README.md
```

---

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/getting-started/installation/)
- Docker running on the host machine
- Your user in the `docker` group: `sudo usermod -aG docker $USER`

---

## Setup

**1. Clone the repository:**

```bash
git clone https://github.com/Festuskipkoech/docker-manager-mcp.git
cd docker-manager-mcp
```

**2. Install dependencies:**

```bash
uv sync
```

**3. Configure your environment (optional):**

```bash
cp .env.example .env
```

The defaults work out of the box on Linux and macOS. No tokens or credentials needed.

```
DOCKER_HOST=unix:///var/run/docker.sock
DEFAULT_LOG_LINES=50
DEFAULT_STOP_TIMEOUT=10
```

---

## Running Locally

```bash
uv run python server.py
```

Or with the FastMCP CLI on Streamable HTTP transport:

```bash
fastmcp run server.py:mcp --transport streamable-http
```

---

## Testing with MCP Inspector

Start the server in one terminal:

```bash
fastmcp run server.py:mcp --transport streamable-http
```

Launch the Inspector in a second terminal:

```bash
npx -y @modelcontextprotocol/inspector
```

In the Inspector UI:

- **Transport:** Streamable HTTP
- **URL:** `http://127.0.0.1:8000/mcp`
- Click **Connect**

**Recommended test sequence:**

| Step | Tool | Input |
|---|---|---|
| 1 | `list_containers` | `{"all_containers": false}` |
| 2 | `get_container_logs` | `{"container_name": "your_container", "lines": 20}` |
| 3 | `inspect_container` | `{"container_name": "your_container"}` |
| 4 | `get_container_stats` | `{"container_name": "your_container"}` |
| 5 | `stop_container` | `{"container_name": "your_container"}` |
| 6 | `start_container` | `{"container_name": "your_container"}` |

---

## Using with Claude Desktop

Add the following to `~/.config/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "docker-manager": {
      "command": "/home/your-user/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/docker-manager-mcp",
        "python",
        "server.py"
      ]
    }
  }
}
```

Use the full path to `uv` (find it with `which uv`). Restart Claude Desktop after saving, then try:

```
List all my running Docker containers and show me their status and ports
```

Claude calls `list_containers` and returns your full container stack:

![Claude listing all running Docker containers](../mcp-assets/docker-1.png)

Inspect a container and check live resource usage:

```
Inspect the prepwise_postgres container and show me its CPU and memory usage
```

![Container inspect and stats results in Claude Desktop](../mcp-assets/docker-2.png)

---

## Running with Docker

When running the server itself inside a container, mount the Docker socket so it can reach the host daemon:

```bash
docker build -t docker-manager-mcp .
docker run -v /var/run/docker.sock:/var/run/docker.sock -p 8000:8000 docker-manager-mcp
```

---

## Troubleshooting

| Error | Cause | Fix |
|---|---|---|
| `Cannot connect to Docker daemon` | Docker not running or socket inaccessible | Run `docker ps` to verify Docker is up |
| `Permission denied on socket` | User not in docker group | Run `sudo usermod -aG docker $USER` then log out and back in |
| `Container not found` | Wrong name or ID | Run `list_containers` with `all_containers: true` to see all containers |
| `Stats only available for running containers` | Container is stopped | Start the container first with `start_container` |