MCP Dockhand

MCP Dockhand

An MCP (Model Context Protocol) server that exposes the Dockhand API as MCP tools. Manage your entire Docker infrastructure through AI assistants.

API coverage: 88.7% of in-scope Dockhand endpoints (282/318) have an MCP tool — see docs/coverage.md for the full, auto-updated breakdown by area.

Dockhand is a Docker management server that connects to multiple Docker hosts via Hawser agents. This MCP server provides full programmatic access to all Dockhand features.

Features

• 280+ MCP Tools covering the Dockhand API — see docs/coverage.md for exact, auto-updated coverage
• Streamable HTTP Transport (MCP Spec 2025-03-26) for Docker container hosting
• Session-based Auth with auto-relogin on 401
• SSE Support for deploy operations (start, stop, down, restart)
• Environment Filter enforced on all container/stack/image/network/volume endpoints
• Docker Ready with multi-stage build, non-root user, and health checks

Quick Start

Docker (recommended)

docker run -d \
  --name mcp-dockhand \
  -p 8080:8080 \
  -e DOCKHAND_URL=https://your-dockhand-server.com \
  -e DOCKHAND_USERNAME=your-username \
  -e DOCKHAND_PASSWORD=your-password \
  ghcr.io/strausmann/mcp-dockhand:latest

Docker Compose

services:
  mcp-dockhand:
    image: ghcr.io/strausmann/mcp-dockhand:latest
    container_name: mcp-dockhand
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - DOCKHAND_URL=https://your-dockhand-server.com
      - DOCKHAND_USERNAME=your-username
      - DOCKHAND_PASSWORD=your-password

From Source

git clone https://github.com/strausmann/mcp-dockhand.git
cd mcp-dockhand
npm install
npm run build
DOCKHAND_URL=https://your-server.com DOCKHAND_USERNAME=admin DOCKHAND_PASSWORD=secret npm start

Configuration

Securing the transport

/mcp binds 0.0.0.0:8080 by default (see MCP_HOST above), and out of the box — with none ofMCP_ALLOWED_HOSTS, MCP_ALLOWED_ORIGINS, or MCP_AUTH_TOKEN set — it accepts any requestwith no Host/Origin check and no authentication. This is the same behavior mcp-dockhandhas always had, kept as the default deliberately: enabling a check by default would rejectrequests from any client that doesn't reach the server as localhost/127.0.0.1 (a LAN IP, areverse proxy, a Docker network alias), breaking existing deployments on a routine update.

You should turn this on once /mcp is reachable beyond your own machine's loopback interface— the server holds one Dockhand admin credential and every tool call acts with that identity, soanyone who can open an MCP session controls Docker (container exec, host bind-mounts viacreate_container, file read/write, stored git credentials). With no protection configured, theserver logs a [security] WARNING at startup as a reminder. Three independent, all-opt-in layersare available:

1. Host allowlist (MCP_ALLOWED_HOSTS). Once set to a non-empty value, every request to/mcp — POST, GET, and DELETE — is rejected with 403 unless its Host header matchesthe allowlist. This is the primary defense againstDNS-rebinding: a malicious web page cannot makethe operator's browser reach the server under a Host value the allowlist accepts. Set it tohowever your client actually reaches the server — localhost:8080/127.0.0.1:8080 for thedocumented local setup, or, if you connect directly by address rather than throughlocalhost (including the mcp-proxy remote-server setup below), the exact host:port yourclient sends, e.g. 100.100.50.40:8222. Get this wrong and every request is rejected with403 Invalid Host header — check the message, it echoes the Host value it saw.
2. Origin allowlist (MCP_ALLOWED_ORIGINS). Once set, any request that does send anOrigin header not in the list is rejected with 403. A missing Origin header always passes(the SDK's own MCP client and most non-browser tooling never send one), so this is only usefulif a browser-based client talks to /mcp directly; the Host allowlist above is what actuallystops DNS-rebinding.
3. Bearer token (MCP_AUTH_TOKEN). Once set, every /mcp request must carryAuthorization: Bearer <token> or is rejected with 401; the comparison is constant-time.Recommended alongside the Host allowlist for any deployment reachable from more than theoperator's own machine.

# .env — recommended configuration once /mcp is reachable beyond loopback
MCP_ALLOWED_HOSTS=dock-mcp.internal.example.com
# or, connecting directly by address instead of a hostname:
#MCP_ALLOWED_HOSTS=100.100.50.40:8222
MCP_AUTH_TOKEN=<a long random secret, e.g. `openssl rand -hex 32`>

Securing the server with CrowdSec

The server writes an nginx-format access line to stdout for every request,including the ones it rejects, while the structured application log goes tostderr. CrowdSec parses the access lines with its stock collections — no customparser required.

Add an acquisition file on the host running your CrowdSec agent:

source: docker
container_name:
  - mcp-dockhand
labels:
  type: docker
  program: nginx-mcp

Both labels are required, and neither fails loudly if you forget it.type: docker enables crowdsecurity/docker-logs, which unwraps Docker's JSONenvelope. program: nginx-mcp enables crowdsecurity/nginx-logs, which matches onprogram starting with nginx — the -mcp suffix keeps this source distinguishablefrom your other nginx sources. With one label missing the chain simply producesnothing, and nothing reports it.

Once wired up, the stock scenarios apply:

A 403 is worth watching too: it means a request failed the MCP_ALLOWED_HOSTS orMCP_ALLOWED_ORIGINS check, which is what a DNS-rebinding attempt looks like fromhere.

The stock 401 scenario only counts POST. Its filter isevt.Parsed.verb == 'POST' — one literal, not a list. This server serves POST, GETand DELETE on /mcp, and the bearer check runs ahead of all three, so a wrong tokenon GET /mcp or DELETE /mcp returns 401 exactly like POST does — andLePresidente/http-generic-401-bf never counts those. Someone guessingMCP_AUTH_TOKEN over GET /mcp is invisible to it.

This is a property of the upstream scenario, shared with every nginx deployment thatuses it — not something this server's log format can fix. To close it, add a localscenario that drops the verb filter, or matches the three methods this serveranswers on. Until then, treat the row above as "repeated 401 on POST /mcp".

Set TRUSTED_PROXIES before you enable this.Behind a reverse proxy every request arrives from the proxy's address. WithoutTRUSTED_PROXIES that address is what gets logged — so the first ban CrowdSecissues takes out the proxy, and with it every user behind it. Set it to theaddress or subnet your proxy talks from.

The setting is equally deliberate in the other direction: the forwarding headersare only honoured from a peer on that list. Trusting them unconditionally would letany direct caller name an arbitrary third party and have them banned.

One expected side effect: the structured JSON lines share the container's logstream and carry the same program label, so they fail the nginx pattern and countas unparsed in cscli metrics. That is noise, not a fault — no alert, no decision.

MCP Client Configuration

Claude Desktop / Claude Code

Add to your MCP settings:

{
  "mcpServers": {
    "dockhand": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

If the server enforces a bearer token (MCP_AUTH_TOKEN set — seeSecuring the transport), the client must send it as anAuthorization header, or every request is rejected with 401. In Claude Code's.mcp.json, add a headers block — reference an environment variable so the tokennever lives in the (often version-controlled) config file:

{
  "mcpServers": {
    "dockhand": {
      "type": "http",
      "url": "http://your-server:8080/mcp",
      "headers": { "Authorization": "Bearer ${DOCKHAND_MCP_TOKEN}" }
    }
  }
}

Send the token only over an encrypted transport. A bearer over plain http:// on ashared network can be sniffed — terminate TLS at a reverse proxy, or reach the server overa WireGuard/Tailscale/VPN link (the app-layer HTTP is then encrypted by the tunnel).

Export DOCKHAND_MCP_TOKEN in the environment Claude Code is launched from (e.g. from agitignored .env you source before starting). The Host/host:port you connect tomust also be in the server's MCP_ALLOWED_HOSTS if that allowlist is set. For ClaudeDesktop (native config has no headers field), pass the token through the mcp-proxyworkaround below — mcp-proxy forwards an Authorization header via its ownenvironment/args.

Claude Desktop with a remote server (mcp-proxy)

Claude Desktop can fail to connect to a remote mcp-dockhand server (notlocalhost) using the native "url" config above, even though the endpointitself is reachable. The symptom is a generic "not a valid MCP server" errorin Claude Desktop, while a plain browser/curl request to the same URLcorrectly returns {"error":"Invalid or missing session ID"}. This is a knownlimitation of Claude Desktop with remote Streamable HTTP servers, not amcp-dockhand bug.

Workaround: wrap the connection withmcp-proxy, which translatesStreamable HTTP to stdio — a transport Claude Desktop handles reliably:

{
  "mcpServers": {
    "dockhand": {
      "command": "/path/to/mcp-proxy",
      "args": ["--transport", "streamablehttp", "http://your-server:8080/mcp"]
    }
  }
}

All tools load and work correctly through the proxy. Thanks to@deadrubberboy for reporting this andsharing the workaround (#90).

Tool Reference

Containers (27 tools)

Stacks (21 tools)

Images (9 tools)

Environments (18 tools)

Networks (7 tools)

Volumes (9 tools)

Git Stacks (15 tools)

Dashboard & Activity (8 tools)

Auth & Hawser (12 tools)

Audit (4 tools)

Notifications (8 tools)

Registries (10 tools)

System & Settings (19 tools)

Users, Roles & Preferences (20 tools)

Schedules (9 tools)

Auto-Update (3 tools)

Self-help / meta tools (6 tools)

Diagnostics for this MCP server itself, distinct from the Dockhand API tools above —useful for a client or operator asking "is this server healthy and correctly configured?"rather than "is Dockhand healthy?". None of these six take any input arguments, and none ofthem wrap a single Dockhand endpoint the way the tables above do (get_tool_manifest andget_runtime_stats call no Dockhand endpoint at all) — see src/tools/meta.ts.

Notes:

• check_for_update needs outbound network access to api.github.com (GitHub's releasesAPI) — it will degrade to updateAvailable: null rather than fail if that's unreachable.
• No meta tool exposes any secret value. validate_config reports only whether therequired env vars are present (booleans) and whether they authenticate (a boolean +the raw HTTP status code, e.g. 200/401) — never the credential values themselves.self_check reports auth validity the same way. get_runtime_stats' lastError carriesonly a tool name, an error message, and a timestamp — never call arguments or responsepayloads. That error message is not fully opaque, though: for a failed Dockhand APIcall it can embed a slice of the upstream HTTP status and response body (viaDockhandClient's own Dockhand API error: ... returned <status>: <body> message), andit is echoed to whichever MCP client next calls get_runtime_stats — not necessarily theone that hit the original error. It never includes request bodies or credential values,and it is truncated to 500 characters (with an ellipsis marker) before being stored, so anoversized upstream response is never echoed wholesale.

Important Notes

update_stack_env — Merge vs Replace Semantics

The Dockhand REST endpoint PUT /api/stacks/{name}/env has replace-semantics: submitting a partial list of variables silently deletes all other variables from the stack. A single-variable update would wipe everything else.

To prevent accidental data loss, this MCP tool defaults to merge mode:

1. It fetches the current variable list via GET /api/stacks/{name}/env.
2. It merges the incoming variables by key (new values overwrite existing ones on key collision).
3. It writes the full combined list back via PUT.

# Safe partial update — only MY_VAR changes, all others preserved
update_stack_env(environmentId=1, name="my-stack", variables=[{key: "MY_VAR", value: "new"}])

# Explicit full replacement — all other variables are deleted
update_stack_env(environmentId=1, name="my-stack", variables=[...], mode="replace")

Use mode="replace" only when you intentionally want to replace the entire variable set.

Environment ID is Required

Most Docker resource endpoints (containers, stacks, images, networks, volumes) require an environmentId parameter. This maps to the ?env=<id> query parameter in the Dockhand API. Without it, endpoints return empty arrays.

SSE Responses

Deploy operations (start, stop, down, restart, compose update with restart) return Server-Sent Events. The MCP server automatically parses these and returns the final result.

Authentication

The server uses session-based cookie authentication. It automatically:

• Logs in on first request
• Stores the session cookie in memory
• Re-authenticates on 401 responses
• Handles session timeout (24h)

Troubleshooting

Start with LOG_LEVEL=debug. Every Dockhand request then appears with its endpoint,status code and duration, and every line of a single call shares onecall identifier — grep for it to get the whole sequence. The req identifierties those lines back to the access line that started them, and sid coverseverything one client did across its whole session. For requests through the client, ms is the full requestduration — it spans the response body being read, not just the time until theresponse headers arrived, so it reflects what a slow or stalled streamedresponse (e.g. a deploy's SSE output) actually cost — and bytes is the size of thebody that was actually read. (The login and self-check probes bootstrap the client and can't route through it, so their lines log time-to-headers without a bytes field.) A failed Dockhand request additionally logs awarn line carrying errType — the exception name (e.g. TimeoutError, TypeError),a bounded vocabulary rather than free text — so you can filter failures by errortype. That warn line fires both when the request itself failed before anyresponse arrived, and when a response body's read failed partway through (e.g.an SSE stream hitting its timeout mid-stream) — either way ms reflects howlong it took to fail.

Development

# Install dependencies
npm install

# Type check
npm run typecheck

# Build
npm run build

# Run in development mode
DOCKHAND_URL=https://your-server.com \
DOCKHAND_USERNAME=admin \
DOCKHAND_PASSWORD=secret \
npm run dev

Linting

npm run lint lints src/ and tests/ with two rules: no-unused-vars andno-explicit-any. Because typescript-eslint does not support the pinnedtypescript@^7.0.2 compiler — it hard-throws on TS 7.0, not just a peer warning: seetypescript-eslint#10940— the lint runs inside a throwaway node:22 container with pinned TypeScript 5 (thelanguage is identical across TS 5/6/7; only the compiler differs). It mounts src/,tests/ and eslint.config.js read-only, so Docker is required to run it. The samescript runs as a hard gate in CI. Unused imports/locals are additionally caught natively onTS 7 by tsc (noUnusedLocals/noUnusedParameters in tsconfig.tests.json, vianpm run typecheck:tests).

License

MIT