docker-mcp
Let Claude and other AI agents run your home-lab Docker host. You ask, and the agent lists, deploys, updates, debugs and cleans up for you.
What it is
docker-mcp is a single-file Model Context Protocol server. It sits next to the Docker daemon, talks to it through the socket, and exposes 49 tools over JSON-RPC 2.0, so any MCP client (Claude Code, Claude Desktop, ChatGPT connectors and other agents) can manage the host.
It's built on plain Node.js http, dockerode and ws, with no MCP SDK, and its tests mock the Docker API, so npm test runs without a daemon.
What the tools cover
CONTAINERS
Run, start, stop, inspect, exec, logs, stats, wait for healthy, update limits, and recreate on a newer image with a backup.
IMAGES
Pull, build, tag, prune, view layer history, and docker_outdated to compare digests against the registry.
COMPOSE
Up, down, ps, logs, build, pull and restart for whole stacks, by project name or directory.
VOLUMES & NETWORKS
Create, remove, connect and inspect, plus volume backup and restore to tarballs.
JOBS & EVENTS
Long pulls and builds run as async jobs you can poll or cancel. Read the Docker event stream to see what changed.
FILES & SYSTEM
Copy files in and out of containers, check disk usage and host info, and log in to private registries.
Arguments and workflows for every tool are in the usage guide.
Quick start
1. Create an API key for each agent that will connect:
openssl rand -hex 32
Pass each key to the container as API_KEY_<AGENT>. The suffix becomes the agent's name in the audit log, so API_KEY_CLAUDE logs as claude. Give every agent a different key. The server reads the keys once at startup and won't start without at least one. To add or rotate a key, change the variable and recreate the container.
Anyone with Docker access on the host can read the keys with docker inspect, so keep them in an untracked .env file with mode 600, never in the image, a compose file or the repo.
2. Build the image and run it on the Docker host:
docker build -t docker-mcp . mkdir -p audit transfer docker run -d --name docker-mcp --restart unless-stopped \ -p 3001:3001 \ -v /var/run/docker.sock:/var/run/docker.sock \ --group-add "$(stat -c %g /var/run/docker.sock)" \ -v /srv:/srv:ro \ -v "$PWD/transfer:/app/transfer" \ -v "$PWD/audit:/app/audit" \ -e AUDIT_LOG=/app/audit/audit.jsonl \ -e API_KEY_CLAUDE=<secret> \ docker-mcp
3. Check it and connect. Run curl http://<docker-host>:3001/health, then connect Claude Code with the same key:
claude mcp add --transport http docker-mcp http://<docker-host>:3001/mcp \ --header "X-API-Key: <secret>"
The setup guide covers keys, mounts, hardening, and connecting Claude Desktop, ChatGPT and other clients.
Built for a shared host
API KEY PER AGENT
Every request needs a key, and the server won't start without one. API_KEY_<AGENT> puts the agent's name on each audit line.
CONFIRM GATES
Removing images, volumes, networks or stacks needs confirm: true. Gate more tools with a two-phase token.
AUDIT LOG
JSONL for every mutating call, with secrets redacted and keys masked to first4…last4.
SELF-GUARD
It won't stop, remove, rename or recreate its own container, so an agent can't cut off its own access.