Content
# 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:
Inspect a container and check live resource usage:
```
Inspect the prepwise_postgres container and show me its CPU and memory usage
```
---
## 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` |
