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

Optionally, replace the DOCKHAND_USERNAME/DOCKHAND_PASSWORD pair with -e DOCKHAND_API_TOKEN=dh_your-api-token to authenticate with a personal API token instead — see Authentication.

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
      # Optional: use a personal API token instead of the pair above.
      #- DOCKHAND_API_TOKEN=dh_your-api-token

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

(Or, in place of the credential pair, DOCKHAND_API_TOKEN=dh_your-api-token — see Authentication.)

Configuration

Securing the transport

/mcp binds 0.0.0.0:8080 by default (see MCP_HOST above), and out of the box — with none of MCP_ALLOWED_HOSTS, MCP_ALLOWED_ORIGINS, or MCP_AUTH_TOKEN set — it accepts any request with no Host/Origin check and no authentication. This is the same behavior mcp-dockhand has always had, kept as the default deliberately: enabling a check by default would reject requests from any client that doesn't reach the server as localhost/127.0.0.1 (a LAN IP, a reverse 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, so anyone who can open an MCP session controls Docker (container exec, host bind-mounts via create_container, file read/write, stored git credentials). With no protection configured, the server logs a [security] WARNING at startup as a reminder. Three independent, all-opt-in layers are 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 matches the allowlist. This is the primary defense against DNS-rebinding: a malicious web page cannot make the operator's browser reach the server under a Host value the allowlist accepts. Set it to however your client actually reaches the server — localhost:8080/127.0.0.1:8080 for the documented local setup, or, if you connect directly by address rather than through localhost (including the mcp-proxy remote-server setup below), the exact host:port your client sends, e.g. 100.100.50.40:8222. Get this wrong and every request is rejected with 403 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 an Origin 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 useful if a browser-based client talks to /mcp directly; the Host allowlist above is what actually stops DNS-rebinding.
3. Bearer token (MCP_AUTH_TOKEN). Once set, every /mcp request must carry Authorization: Bearer <token> or is rejected with 401; the comparison is constant-time. Recommended alongside the Host allowlist for any deployment reachable from more than the operator'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 to stderr. CrowdSec parses the access lines with its stock collections — no custom parser 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 JSON envelope. program: nginx-mcp enables crowdsecurity/nginx-logs, which matches on program starting with nginx — the -mcp suffix keeps this source distinguishable from your other nginx sources. With one label missing the chain simply produces nothing, 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 or MCP_ALLOWED_ORIGINS check, which is what a DNS-rebinding attempt looks like from here.

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

This is a property of the upstream scenario, shared with every nginx deployment that uses it — not something this server's log format can fix. To close it, add a local scenario that drops the verb filter, or matches the three methods this server answers 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. Without TRUSTED_PROXIES that address is what gets logged — so the first ban CrowdSec issues takes out the proxy, and with it every user behind it. Set it to the address or subnet your proxy talks from.

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

One expected side effect: the structured JSON lines share the container's log stream and carry the same program label, so they fail the nginx pattern and count as 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 — see Securing the transport), the client must send it as an Authorization header, or every request is rejected with 401. In Claude Code's .mcp.json, add a headers block — reference an environment variable so the token never 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 a shared network can be sniffed — terminate TLS at a reverse proxy, or reach the server over a 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 a gitignored .env you source before starting). The Host/host:port you connect to must also be in the server's MCP_ALLOWED_HOSTS if that allowlist is set. For Claude Desktop (native config has no headers field), pass the token through the mcp-proxy workaround below — mcp-proxy forwards an Authorization header via its own environment/args.

Claude Desktop with a remote server (mcp-proxy)

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

Workaround: wrap the connection with mcp-proxy, which translates Streamable 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 and sharing 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 of them wrap a single Dockhand endpoint the way the tables above do (get_tool_manifest and get_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 releases API) — 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 the required 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 carries only a tool name, an error message, and a timestamp — never call arguments or response payloads. That error message is not fully opaque, though: for a failed Dockhand API call it can embed a slice of the upstream HTTP status and response body (via DockhandClient's own Dockhand API error: ... returned <status>: <body> message), and it is echoed to whichever MCP client next calls get_runtime_stats — not necessarily the one 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 an oversized 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 normally authenticates with DOCKHAND_USERNAME + DOCKHAND_PASSWORD and a session cookie. It automatically:

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

Optionally, set DOCKHAND_API_TOKEN to a personal API token instead — create one on your Dockhand profile page, under API tokens (Dockhand v1.0.26+; bearer auth did not work with an enterprise license in v1.0.25). The token acts as the user who created it, with that user's roles. Every request then carries Authorization: Bearer <token>: no login round-trip, no session cookie to expire, and no re-login on 401. The token also works against an account with MFA enabled, where the session login above cannot complete a TOTP challenge non-interactively.

When DOCKHAND_API_TOKEN is set it is used and the username/password pair is ignored (a warning is logged when both are set), so the pair is not required alongside it. With neither the token nor a complete credential pair, the server exits at startup rather than failing every tool call later. The same happens for a token that is not dh_… base64url text (for example one with a line break from copy/paste); the error names the variable, never its value.

A rejected token is not retried: Dockhand puts an IP into a 5-minute cooldown (HTTP 429) after 15 failed bearer attempts per minute, which would hit every client behind the same address. A revoked or expired token therefore fails fast with an error that names DOCKHAND_API_TOKEN.

Limitations in token mode. Some Dockhand endpoints read only the session cookie (validateSession) or refuse bearer auth on purpose, so these tools do not work with DOCKHAND_API_TOKEN (their descriptions say so too):

Use the username/password pair for these, or the Dockhand UI.

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 one call identifier — grep for it to get the whole sequence. The req identifier ties those lines back to the access line that started them, and sid covers everything one client did across its whole session. For requests through the client, ms is the full request duration — it spans the response body being read, not just the time until the response headers arrived, so it reflects what a slow or stalled streamed response (e.g. a deploy's SSE output) actually cost — and bytes is the size of the body 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 a warn line carrying errType — the exception name (e.g. TimeoutError, TypeError), a bounded vocabulary rather than free text — so you can filter failures by error type. That warn line fires both when the request itself failed before any response 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 how long 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

Dockhand API spec

MCP tool routes, query parameters, and request-body contracts are all derived from a single pinned source, docs/dockhand-openapi.json — fetched from a fixed upstream Finsys/dockhand commit by scripts/fetch-openapi.mjs (the pin is mirrored in src/openapi/pinned.ts and kept in sync with SOURCE_COMMIT in that script).

• npm run api:validate is a hard, PR-blocking CI gate: it fails the build on route/query mismatches and on a tool missing a required body field (BODY_PARAM_MISSING_REQUIRED); other body-contract findings (unknown body fields, untyped passthrough, unresolved contracts, missing tools) stay advisory-only — see docs/body-contract-report.md.
• npm run api:coverage-doc and npm run api:tool-endpoint-map regenerate the derived docs (docs/coverage.md, src/openapi/tool-endpoint-map.ts, docs/body-contract-report.md); CI checks they're in sync with the code on every PR.
• A weekly workflow (.github/workflows/drift-bump.yml) bumps the pinned commit toward upstream main and opens a PR — no auto-merge, so any body-contract drift from a new Dockhand release is caught by the hard gate above before it ships.
• Version-gating (comparing the live Dockhand server's version against the pinned spec) is a separate, not-yet-implemented follow-up.

Linting

npm run lint lints src/ and tests/ with two rules: no-unused-vars and no-explicit-any. Because typescript-eslint does not support the pinned typescript@^7.0.2 compiler — it hard-throws on TS 7.0, not just a peer warning: see typescript-eslint#10940 — the lint runs inside a throwaway node:22 container with pinned TypeScript 5 (the language 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 same script runs as a hard gate in CI. Unused imports/locals are additionally caught natively on TS 7 by tsc (noUnusedLocals/noUnusedParameters in tsconfig.tests.json, via npm run typecheck:tests).

Testing conventions

These grew out of the test-hardening review of PRs #210–#215 (Issue #224) — several tests there passed while proving nothing. Two mechanical rules and one habit came out of it, and are enforced or expected repo-wide:

noUnusedLocals / noUnusedParameters stay on for tests. They are set in tsconfig.tests.json and checked by npm run typecheck:tests (part of CI). The reason to keep them, spelled out: a value parsed from output into a local that is then never asserted on is a dead assertion — a test that looks like it checks something but doesn't. With these flags on, that is a compile error instead of a silently green test. Do not relax them for test files, and do not add a per-file tsconfig under tests/ to opt a file back out.

A negative assertion must name the field it denies. expect(raw).not.toContain('42') over a whole serialized blob is a coincidence waiting to happen — it can also match a timestamp, an id, or an unrelated field, so it can fail for the wrong reason (or, for a keyword sweep, fail because an unrelated legitimate field's name happens to contain the word). Real case in #215: not.toContain('42') collided with a timestamp. Parse the output and assert on the specific field (obj.route, obj.err.type) instead of the raw string. When the whole point of the check is "no unexpected field anywhere in the tree carries this", walk the object (see walkEntries() in tests/tools/meta.self-check.test.ts, or quotedFields() / statusBytesSegment() in tests/access-log.test.ts) and name the offending path in the assertion message — do not fall back to JSON.stringify(value) plus a blind regex.

Counter-check every new regression test against the un-fixed code, once. If a test stays green against the version of the code it exists to catch, it proves nothing — a fallback path, a duplicate-key dedupe, or an env-driven later failure can all keep a test green for the wrong reason (all three happened across #214/#215). Before considering a new regression test done: revert the fix (or otherwise reintroduce the bug) locally, run the test, confirm it fails for the reason the test claims to check, then restore the fix.

License

MIT