Docker Container Manager 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 using FastMCP, 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
• Docker running on the host machine
• Your user in the docker group: sudo usermod -aG docker $USER

---

Setup

1. Clone the repository:

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

2. Install dependencies:

uv sync

3. Configure your environment (optional):

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

uv run python server.py

Or with the FastMCP CLI on Streamable HTTP transport:

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

---

Testing with MCP Inspector

Start the server in one terminal:

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

Launch the Inspector in a second terminal:

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:

{
  "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:

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