A weekday container check
Prompt
Every weekday at 9:00, list my Docker containers with their status, tell me which ones are not running that were running yesterday, and for each of those show the last twenty lines of its logs.
Verified MCP server: Docker
The Docker MCP server, verified live on a real Mac.
- Verified2026-08-03macOS 26.3.1
- Packagemcp-server-docker (PyPI) 0.2.1
- Self-reporteddocker-server 1.29.0
- MCP protocol2025-06-18
- RuntimePython 3.12.11 (uvx)
The short answer
Last verified 2026-08-03
The Docker MCP server lets an AI assistant drive Docker on your own Mac: list containers, read their logs, start and stop them, pull and build images, and manage networks and volumes. It is a community package called mcp-server-docker, it is not Docker Inc. software, and it asks for no API key and no account, because it reaches the daemon through the same local socket the docker command uses. What it does need is Docker itself running: with the daemon unreachable the server crashes before it can say hello, and we captured that crash too. We did not take the README's word for any of it. We started Docker, spawned the server, spoke the protocol to it, enumerated all nineteen tools, ran real calls against this Mac's own Docker state, and kept the raw output, including the exact errors it returns when a container, an image or a network does not exist. All of it is on this page. [1][3][6]
Verification
How this MCP server was verified.
Method
We started Docker Desktop on the test Mac, then spawned the server with uvx over stdio with no environment variables set, completed the MCP initialize handshake, called tools/list, and ran eight real tool calls across three sessions. Four of them answered from this Mac's own Docker state: list_networks, list_volumes, and list_containers twice, and the sample below is one of them. Four were meant to fail and did, which is where the troubleshooting section comes from. Nothing we called created, changed or removed anything: the three calls that could have changed something all named things that do not exist and came back with a 404. A fourth session, started with DOCKER_HOST pointed at a socket that is not there, reproduced the crash you get when Docker is not running, and never reached the handshake at all. The Mac ran Docker Desktop 4.5.0 with Engine 20.10.12 and Docker API 1.41; uvx resolved mcp-server-docker 0.2.1 onto Python 3.12.11 with docker-py 7.2.0 and the Python MCP SDK 1.29.0. The server prints nothing at all on startup, on stdout or stderr, so the banner below is the raw one-line initialize response as it came off the wire.
Startup banner
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"experimental":{},"prompts":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"tools":{"listChanged":false}},"serverInfo":{"name":"docker-server","version":"1.29.0"}}}One real tool call
tools/call list_networks {}[
{
"id": "dcf9d8f81c4ca5896a85a1eedface31f2a8e7db9cc115f417485ea467215c7aa",
"name": "bridge",
"short_id": "dcf9d8f81c4c",
"driver": "bridge",
"scope": "local",Real lines from the captured result: enough to prove the call answered.
Tools
Every tool, enumerated from the running server.
The server answered tools/list with 19 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| list_containersallfilters | List all Docker containers |
| create_containerdetachimage*nameentrypointcommandnetworkenvironmentportsvolumeslabelsauto_remove | Create a new Docker container |
| run_containerdetachimage*nameentrypointcommandnetworkenvironmentportsvolumeslabelsauto_remove | Run an image in a new Docker container (preferred over `create_container` + `start_container`) |
| recreate_containerdetachimage*nameentrypointcommandnetworkenvironmentportsvolumeslabelsauto_removecontainer_id | Stop and remove a container, then run a new container. Fails if the container does not exist. |
| start_containercontainer_id* | Start a Docker container |
| fetch_container_logscontainer_id*tail | Fetch logs for a Docker container |
| stop_containercontainer_id* | Stop a Docker container |
| remove_containercontainer_id*force | Remove a Docker container |
| list_imagesnameallfilters | List Docker images |
| pull_imagerepository*tag | Pull a Docker image |
| push_imagerepository*tag | Push a Docker image |
| build_imagepath*tag*dockerfile | Build a Docker image from a Dockerfile |
| remove_imageimage*force | Remove a Docker image |
| list_networksfilters | List Docker networks |
| create_networkname*driverinternallabels | Create a Docker network |
| remove_networknetwork_id* | Remove a Docker network |
| list_volumes | List Docker volumes |
| create_volumename*driverlabels | Create a Docker volume |
| remove_volumevolume_name*force | Remove a Docker volume |
Parameters marked with * are required.
Setup
Working configs, one per app.
Copy the block for the app you use. Each one is the configuration this server was verified with.
Claude Desktop
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"docker": {
"command": "uvx",
"args": [
"mcp-server-docker"
]
}
}
}No environment variables and no folder argument: the server finds your local Docker by itself. Start Docker Desktop first, then quit and reopen Claude Desktop. If the server does not appear, put the full path printed by which uvx in the command field, because a Mac app launched from the Dock does not always inherit your shell PATH. [10][5]
Claude Code
One command in your terminal:
claude mcp add docker -- uvx mcp-server-docker
Everything after the double dash is the exact command Claude Code will run, and it is the command we verified. Make sure Docker is running before you start a session, or the server will die at launch. [11]
Cursor
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"docker": {
"command": "uvx",
"args": [
"mcp-server-docker"
]
}
}
}Cursor picks the file up on restart. To drive a Docker engine on another machine instead of the local one, add an env object with DOCKER_HOST set to an ssh:// address, which the server supports through the Python Docker SDK. [12][5]
Routines
No JSON file and no terminal. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name Docker Command uvx Arguments mcp-server-docker
Leave Environment Variables empty. Start Docker Desktop before you click Test Connection: a working server answers with its tool count, nineteen for this one, and a stopped Docker gives you a dead server instead. [13]
No terminal needed
Set the Docker MCP server up without the terminal.
If you have never opened Terminal and would rather keep it that way, this is your path, with one unavoidable exception noted in the first step. Routines is a Mac app that runs MCP servers for you: fill in three fields once, and this server's tools are available to your AI in chat and in scheduled routines.
01
Install Routines, uv, and Docker
Download the app from getroutines.ai/download, drag it to Applications, and sign in. This server is Python, so it also needs uv, the tool that provides the uvx command: install it from astral.sh/uv, or with one terminal line if you already use Homebrew, brew install uv. And it needs Docker Desktop from docker.com, since the whole point is to drive the Docker running on your Mac.
02
Open the MCP settings
Click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.
03
Choose Command (stdio)
The form opens in URL mode. Switch it to Command (stdio): this server is a command that runs on your Mac, not a web address.
04
Fill in three fields
Name: Docker. Command: uvx. Arguments: mcp-server-docker, on its own, with nothing after it. There is no folder to allow and no key to paste, because the server talks to Docker through the local socket your own account already has access to.
05
Test, then add
Leave Environment Variables empty, this server needs none. Open Docker Desktop and wait for the whale in the menu bar to stop animating, then click Test Connection: Routines starts the server and reports how many tools it found, nineteen for this one. Then click Add Server.
06
Use it
The tools work in chat right away, so you can ask which containers are running and why one of them keeps restarting. To let a scheduled routine use them, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Routines worth scheduling.
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
A Monday disk tidy-up list
Prompt
Every Monday at 8:00, list my Docker images and volumes, flag every one that no container is using, and give me the list so I can decide what to remove myself.
A Friday error sweep
Prompt
Every Friday at 17:00, fetch the last hundred log lines from each running container, and write me one short paragraph per container about anything that looks like an error or a repeated warning.
Troubleshooting
The errors we hit, and what fixed them.
Real errors captured during the verification run, printed exactly as the server returned them.
The server dies the moment your client starts it
What you see
docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))The fix
Docker is not running, or the server is looking for it in the wrong place. This is not a soft failure you can work around inside the chat: the package calls docker.from_env() before it opens the MCP connection, so the process exits before your client can finish the handshake, and all your client tells you is that the server is dead. We reproduced it on purpose by pointing DOCKER_HOST at a socket that does not exist. Start Docker Desktop, wait for the whale in the menu bar to settle, and restart your MCP client. If you set DOCKER_HOST yourself, check the address in it.
No such container
What you see
404 Client Error for http+docker://localhost/v1.41/containers/no-such-container-mcp-verify/json: Not Found ("No such container: no-such-container-mcp-verify")The fix
The name or id reached Docker and Docker does not have it: usually a typo, a container that was removed, or one that only exists on a different machine. We triggered this on purpose with a made-up name. Ask for list_containers with all set to true first, then repeat the request with a name from that list. Removed networks and volumes come back the same way, with their own 404.
Pull access denied for an image
What you see
404 Client Error for http+docker://localhost/v1.41/images/create?tag=latest&fromImage=mcp-verify-no-such-image-2026: Not Found ("pull access denied for mcp-verify-no-such-image-2026, repository does not exist or may require 'docker login': denied: requested access to the resource is denied")The fix
The registry either has no such repository or will not show it to you. The message covers both cases at once, and we triggered it with an image name that does not exist. Check the spelling and the tag, and if the image is private, make sure this Mac is already signed in to that registry before you ask: none of the nineteen tools can log you in, so the server cannot fix it mid-conversation.
Your MCP client cannot start the server at all
The fix
The uvx command belongs to uv. If uv is not installed, every client on this page fails at the spawn step before the server can say anything. Install it from astral.sh/uv, then run which uvx in a terminal: if it prints a path but a Mac app still cannot start the server, paste that full path into the command field, because an app launched from the Dock does not always inherit your shell PATH.
FAQ
Questions people ask.
What is the Docker MCP server?
It is a small Python program that sits between an AI assistant and the Docker running on your Mac. Once connected, Claude can list your containers and images, read container logs, start and stop containers, pull and build images, and create or remove networks and volumes, all through the ordinary Docker API. It runs as a local process and talks to your AI app over stdio. [5][6]
What tools does the Docker MCP server include?
The running server exposes 19 tools: containers (list_containers, create_container, run_container, recreate_container, start_container, fetch_container_logs, stop_container, remove_container), images (list_images, pull_image, push_image, build_image, remove_image), networks (list_networks, create_network, remove_network), and volumes (list_volumes, create_volume, remove_volume). The table above is the live tools/list output, word for word. The same handshake also advertises prompt and resource capabilities, and the README describes one prompt for Compose deployments and per-container stats and logs as resources. [5]
Is this Docker's official MCP server?
No. mcp-server-docker is a community package by Christian Kreiling, with 731 stars on GitHub and no release since June 2025. Docker Inc. does publish MCP software, but it is a different thing: the MCP Toolkit, built on the open-source docker/mcp-gateway, is a gateway that runs other people's MCP servers as containers, and mcp.docker.com redirects to Docker's catalogue of them at hub.docker.com/mcp. That is the inverse of what this page covers, which is a server that lets an assistant manage Docker itself. We did not test the Toolkit: it needs a much newer Docker Desktop than the one on our test Mac. [3][7][8][9]
Is the Docker MCP server safe?
Treat it as powerful, not sandboxed. There is no allow-list here the way the filesystem server has folders: whatever your account can do to Docker, this server can do, and only five of its nineteen tools are read-only, so the other fourteen change something, including remove_container, remove_image and remove_volume. The project says so itself, in capitals: do not configure containers with sensitive data, and review the containers the model creates. It does refuse the most dangerous options, with no support for privileged mode or capability flags. Read what the assistant proposes before you approve it, and keep it away from anything you cannot rebuild. [5]
Does it need an API key or an account?
No. There is nothing to sign up for and no credential to paste: the server reaches Docker over the local socket your own macOS account already has access to. It does need Docker itself to be running, which is the one prerequisite this page keeps repeating, and the uvx command downloads the package from the public PyPI registry on first run, so the very first start needs an internet connection. After that it is cached on your Mac. [1][5]
Why does the server report version 1.29.0 in the handshake?
Because it does not report one of its own. The source creates its MCP server as Server("docker-server") with no version argument, so the SDK falls back to printing its own package version, and our run resolved that SDK to 1.29.0. The package we installed is mcp-server-docker 0.2.1, published on 2025-06-05. Both numbers are real and both are captured above. [1][6]
What licence is it under?
GPL-3.0, which is unusual in this directory: most MCP servers here are MIT or Apache-2.0. The repository ships the full GNU General Public License version 3, and GitHub reports the same. That matters if you plan to fork it into something you distribute; it does not affect running it on your own machine. [4][3]
Sources
Every external claim, receipted.
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
PyPI registry: mcp-server-dockeraccessed 2026-08-03Latest version 0.2.1, uploaded 2025-06-05; author Christian Kreiling; requires Python >=3.12 and declares docker>=7.1.0, mcp>=1.1.0,<2.0 and paramiko>=3.5.1,<4.0.
[2]
PyPI download stats: mcp-server-dockeraccessed 2026-08-033,571 downloads in the last week and 12,821 in the last month at access time.
[3]
GitHub: ckreiling/mcp-server-dockeraccessed 2026-08-03731 stars, licence reported as GPL-3.0, and a last push dated 2025-06-05 at access time, per the GitHub API.
[4]
ckreiling/mcp-server-docker LICENSE fileaccessed 2026-08-03The full GNU General Public License version 3. PyPI carries no licence classifier for this package, only the licence text.
[5]
mcp-server-docker READMEaccessed 2026-08-03The uvx config shape, the docker_compose prompt, the per-container stats and logs resources, the ssh:// DOCKER_HOST option, and the disclaimers about sensitive data and unsupported privileged options.
[6]
mcp-server-docker source: server.py and __init__.pyaccessed 2026-08-03Line 34 creates Server("docker-server") with no version, and run_stdio() uses stdio_server(): the server speaks stdio and declares no version of its own. In __init__.py, docker.from_env() is evaluated before the stdio server starts, which is why an unreachable daemon is a startup crash.
[7]
docs.docker.com: MCP Catalog and Toolkitaccessed 2026-08-03Docker Inc.'s own MCP surface: a Docker Desktop feature that runs other MCP servers as containers behind one local gateway.
[8]
GitHub: docker/mcp-gatewayaccessed 2026-08-031,516 stars, MIT licence, and a push dated 2026-07-23 at access time. The open-source CLI plugin behind the MCP Toolkit; its README lists Docker Desktop 4.59 or newer as a prerequisite, and our test Mac runs 4.5.0.
[9]
Docker MCP Catalog on Docker Hubaccessed 2026-08-03Docker's public catalogue of MCP servers packaged as images. A request to mcp.docker.com answered 302 to this address at access time.
[10]
modelcontextprotocol.io: Connect to local MCP serversaccessed 2026-08-03The Claude Desktop config file path and the mcpServers command and args shape.
[11]
Claude Code docs: MCPaccessed 2026-08-03The claude mcp add [options] <name> -- <command> [args...] syntax for local stdio servers.
[12]
[13]
Routines: Connectorsaccessed 2026-08-03How Routines runs one-click OAuth connectors and any MCP server.
This page describes Docker as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. Your notes stay markdown files on your Mac, there is no cloud bill, and it works offline. Download Routines