Docker MCP server

1# 🐋 Docker MCP server
2 
3An MCP server for managing Docker with natural language!
4 
5## 🪩 What can it do?
6 
7- 🚀 Compose containers with natural language
8- 🔍 Introspect & debug running containers
9- 📀 Manage persistent data with Docker volumes
10 
11## ❓ Who is this for?
12 
13- Server administrators: connect to remote Docker engines for e.g. managing a
14  public-facing website.
15- Tinkerers: run containers locally and experiment with open-source apps
16  supporting Docker.
17- AI enthusiasts: push the limits of that an LLM is capable of!
18 
19## Demo
20 
21A quick demo showing a WordPress deployment using natural language:
22 
23https://github.com/user-attachments/assets/65e35e67-bce0-4449-af7e-9f4dd773b4b3
24 
25## 🏎️ Quickstart
26 
27### Install
28 
29#### Claude Desktop
30 
31On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
32 
33On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
34 
35<details>
36  <summary>Install from PyPi with uv</summary>
37 
38If you don't have `uv` installed, follow the installation instructions for your
39system:
40[link](https://docs.astral.sh/uv/getting-started/installation/#installation-methods)
41 
42Then add the following to your MCP servers file:
43 
44```
45"mcpServers": {
46  "mcp-server-docker": {
47    "command": "uvx",
48    "args": [
49      "mcp-server-docker"
50    ]
51  }
52}
53```
54 
55</details>
56 
57<details>
58  <summary>Install with Docker</summary>
59 
60Purely for convenience, the server can run in a Docker container.
61 
62After cloning this repository, build the Docker image:
63 
64```bash
65docker build -t mcp-server-docker .
66```
67 
68And then add the following to your MCP servers file:
69 
70```
71"mcpServers": {
72  "mcp-server-docker": {
73    "command": "docker",
74    "args": [
75      "run",
76      "-i",
77      "--rm",
78      "-v",
79      "/var/run/docker.sock:/var/run/docker.sock",
80      "mcp-server-docker:latest"
81    ]
82  }
83}
84```
85 
86Note that we mount the Docker socket as a volume; this ensures the MCP server
87can connect to and control the local Docker daemon.
88 
89</details>
90 
91## 📝 Prompts
92 
93### 🎻 `docker_compose`
94 
95Use natural language to compose containers. [See above](#demo) for a demo.
96 
97Provide a Project Name, and a description of desired containers, and let the LLM
98do the rest.
99 
100This prompt instructs the LLM to enter a `plan+apply` loop. Your interaction
101with the LLM will involve the following steps:
102 
1031. You give the LLM instructions for which containers to bring up
1042. The LLM calculates a concise natural language plan and presents it to you
1053. You either:
106   - Apply the plan
107   - Provide the LLM feedback, and the LLM recalculates the plan
108 
109#### Examples
110 
111- name: `nginx`, containers: "deploy an nginx container exposing it on port
112  9000"
113- name: `wordpress`, containers: "deploy a WordPress container and a supporting
114  MySQL container, exposing Wordpress on port 9000"
115 
116#### Resuming a Project
117 
118When starting a new chat with this prompt, the LLM will receive the status of
119any containers, volumes, and networks created with the given project `name`.
120 
121This is mainly useful for cleaning up, in-case you lose a chat that was
122responsible for many containers.
123 
124## 📔 Resources
125 
126The server implements a couple resources for every container:
127 
128- Stats: CPU, memory, etc. for a container
129- Logs: tail some logs from a container
130 
131## 🔨 Tools
132 
133### Containers
134 
135- `list_containers`
136- `create_container`
137- `run_container`
138- `recreate_container`
139- `start_container`
140- `fetch_container_logs`
141- `stop_container`
142- `remove_container`
143 
144### Images
145 
146- `list_images`
147- `pull_image`
148- `push_image`
149- `build_image`
150- `remove_image`
151 
152### Networks
153 
154- `list_networks`
155- `create_network`
156- `remove_network`
157 
158### Volumes
159 
160- `list_volumes`
161- `create_volume`
162- `remove_volume`
163 
164## 🚧 Disclaimers
165 
166### Sensitive Data
167 
168**DO NOT CONFIGURE CONTAINERS WITH SENSITIVE DATA.** This includes API keys,
169database passwords, etc.
170 
171Any sensitive data exchanged with the LLM is inherently compromised, unless the
172LLM is running on your local machine.
173 
174If you are interested in securely passing secrets to containers, file an issue
175on this repository with your use-case.
176 
177### Reviewing Created Containers
178 
179Be careful to review the containers that the LLM creates. Docker is not a secure
180sandbox, and therefore the MCP server can potentially impact the host machine
181through Docker.
182 
183For safety reasons, this MCP server doesn't support sensitive Docker options
184like `--privileged` or `--cap-add/--cap-drop`. If these features are of interest
185to you, file an issue on this repository with your use-case.
186 
187## 🛠️ Configuration
188 
189This server uses the Python Docker SDK's `from_env` method. For configuration
190details, see
191[the documentation](https://docker-py.readthedocs.io/en/stable/client.html#docker.client.from_env).
192 
193### Connect to Docker over SSH
194 
195This MCP server can connect to a remote Docker daemon over SSH.
196 
197Simply set a `ssh://` host URL in the MCP server definition:
198 
199```
200"mcpServers": {
201  "mcp-server-docker": {
202    "command": "uvx",
203    "args": [
204      "mcp-server-docker"
205    ],
206    "env": {
207      "DOCKER_HOST": "ssh://myusername@myhost.example.com"
208    }
209  }
210}
211```
212 
213## 💻 Development
214 
215Prefer using Devbox to configure your development environment.
216 
217See the `devbox.json` for helpful development commands.
218 
219After setting up devbox you can configure your Claude MCP config to use it:
220 
221```
222  "docker": {
223    "command": "/path/to/repo/.devbox/nix/profile/default/bin/uv",
224    "args": [
225      "--directory",
226      "/path/to/repo/",
227      "run",
228      "mcp-server-docker"
229    ]
230  },
231```
232