Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@dockhand-mcp list all running containers"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A security-first Model Context Protocol server for DockHand. It lets MCP clients (Claude Code, Claude Desktop, the MCP Inspector, any client that can send a header) inspect and operate the Docker environments DockHand manages, through DockHand's REST API only, and never through the Docker socket.
Why: an AI client that can manage containers is useful, and dangerous if it can do everything DockHand can. dockhand-mcp exposes a curated, profile-gated subset of DockHand's API: the whole server is designed around what a prompt-injected model must not be able to do.
Status: early (v0.1.x). Built and tested against DockHand's API 1.0.46. Before 1.0, tool
names, arguments, results and configuration can change in a minor release; each release's notes
list what changed, so pin the image by digest and read them before upgrading. Tools whose
DockHand response shape is not documented are marked experimental in
docs/TOOLS.md. OAuth, which Claude.ai custom connectors need, is not
available yet (CLIENTS §4).
Profiles. read-only (the server's default), operator (plus reversible writes: start,
stop, deploy, compose and .env edits verified by reading them back) and admin (plus
destructive tools). Tools above the profile are never registered, so no client can list or call
them. The profile is set by the server's configuration, never by the client.
Excluded tier. Whole API families are out in every profile, permanently: credentials and tokens, users and roles, in-container exec and file access, the DockHand host filesystem, secret providers, image export, self-update, webhooks (SECURITY §4).
Human-approved destructive actions. Every remove, prune, stack down and delete needs a human
approval: an elicitation form bound to the exact call where the client supports it, otherwise
an explicit confirm (weaker: see Confirm mode and approvals).
Destructive calls are also rate-limited per client.
Output redaction. DockHand's answers pass one redactor before they reach the model: credential-shaped keys, tokens and URL credentials, and each stack's own variable values in its operation output (SECURITY §2).
Guardrails on compose writes. Privileged containers, host-namespace modes, dangerous
capabilities and bind mounts of /, the Docker socket, /etc and similar are refused before
anything is written.
No socket, no shell, no host mounts. The server is a plain HTTP client of DockHand. It runs as a non-root, read-only, capability-free container.
Authenticated before anything. Bearer-token auth on every MCP request, including tool listing, with rate limits and DNS-rebinding protection.
Scanned and signed image. Each release image is scanned with OSV-Scanner for both platforms before it is pushed, signed keylessly with cosign, and published with a CycloneDX SBOM; the published image is rescanned weekly.
Fail-closed startup. An invalid or insecure configuration, or a missing DockHand token when DockHand requires one, stops the server with a one-line reason instead of starting it.
Design and threat model: docs/SECURITY.md. Locked decisions:
plan.md.
Related MCP server: Docker-MCPilotS
You need a DockHand API token first: docs/DOCKHAND-SETUP.md walks
through the dedicated user, the Enterprise role or the Free-edition warning, and the token.
Copy deploy/docker-compose.yml into a new directory. Its
image: line is a placeholder, ghcr.io/tyler-rich/dockhand-mcp:X.Y.Z@sha256:<digest>:
replace it with the exact pinned image: line from the latest GitHub
release notes, and set DOCKHAND_URL and DOCKHAND_MCP_ALLOWED_HOSTS.
Create the two token files. The DockHand token file is required: without it the server won't start (unless DockHand runs with authentication off).
mkdir -p secrets && chmod 700 secrets
$EDITOR secrets/dockhand_token # paste the dh_ token
python -c "import secrets;print(secrets.token_urlsafe(48))" > secrets/mcp_token
chmod 600 secrets/* && sudo chown 10001:10001 secrets/* # the container runs as UID 10001Check, then start:
docker compose run --rm dockhand-mcp check
docker compose up -d
docker compose ps # dockhand-mcp should become "healthy"Connect a client with the token in secrets/mcp_token: docs/CLIENTS.md.
The reference compose runs profile operator: switch to admin only while you need
destructive tools. If the container keeps restarting, its last log line says why:
troubleshooting. Other ways to run it:
deploy/docker-run.md (plain Docker),
deploy/dockhand-stack.yml (DockHand or Portainer stack editors),
stdio for Claude Desktop (CLIENTS §3).
Verify the image signature before you deploy it; each release's notes carry the exact
cosign verify line.
Keep secrets out of compose files. dockhand_get_stack_compose returns compose files as
they are, so that they can be edited; a literal password in a compose file reaches the model.
Keep secrets in the stack's environment or DockHand's secret variables and reference them as
${NAME}. More.
Never point two DockHand environments at one Docker daemon. Each would list the other's
stacks, duplicates become possible, and compose down through one removes the other's
containers. The server guards what it can, and dockhand-mcp check warns when it detects a
shared daemon. More.
Every setting is an environment variable; *_FILE reads the value from a file, for example a
Docker secret. deploy/.env.example lists them all with their defaults.
Variable | Default | Notes |
| (required) | e.g. |
|
| Boolean ( |
| (required unless DockHand auth is disabled — see SECURITY §6) |
|
| — | PEM path for private CAs. |
|
| Disables verification. WARN at startup. |
| — | Makes |
|
|
|
| — | Comma list of tool names to remove. |
|
|
|
|
| Compose sets bind to |
|
| |
|
|
|
| (required in bearer mode) | ≥ 32 bytes of entropy enforced (min length 43 base64url chars). |
|
| Required to be |
|
| Host-header allow-list (DNS rebinding). Add your public hostname. |
| (empty = no browser origins) | Origin allow-list. |
|
| Honour |
|
| Per client IP. |
|
| Seconds, for |
|
| |
|
|
|
| — | Comma list of extra bind-mount source prefixes to allow (SECURITY §5). The non-configurable deny set can never be allowed. Implemented in S3a; parsed and validated from S0. |
|
|
|
| (random per process) | HMAC key for elicitation challenges. Optional: if unset, a random 32-byte key is generated at startup (challenges then don't survive a restart, which is fine at a 120 s lifetime). If set, ≥ 32 bytes. |
|
| Per-principal destructive-call rate limit (S-11). Every destructive |
|
| Deliberately ugly escape hatch; see SECURITY §6. |
| — | Phase 5 only. Not parsed before the OAuth implementation session; listed so the names are reserved. |
96 tools in three tiers, each registered only in the profiles that include its tier:
Tier | Profiles | Tools | Examples |
read |
| 50 | environments, containers (list, inspect, logs, stats), stacks (list, compose, |
operator |
| 36 | container and stack lifecycle, compose and |
destructive |
| 10 | remove container, image, volume or network; stack down and delete; prune; batch remove; run image prune now; clear activity log |
The full catalogue, with each tool's DockHand endpoints and permissions:
docs/TOOLS.md. dockhand-mcp tools prints the catalogue of the running version
(names, descriptions, schema hashes) so you can diff it between upgrades.
Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
Some third-party dependencies carry their own licenses; each release's SBOM lists them.
Contributions are welcome under the same license: per Section 5 of the Apache License 2.0, any
contribution you intentionally submit is licensed under its terms, with no additional terms or
conditions. How to propose a change: CONTRIBUTING.md. Report security issues
privately: SECURITY.md.
Not affiliated with or endorsed by DockHand. DockHand is a trademark of its respective owner.
This server cannot be deployed
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Security & DLP proxy for MCP: tool-poisoning scans, PII redaction on tool args/results. Beta.
