MCP Dockhand

Ein MCP-Server (Model Context Protocol), der die Dockhand-API als MCP-Tools bereitstellt. Verwalten Sie Ihre gesamte Docker-Infrastruktur über KI-Assistenten.

API-Abdeckung: 88.7% der im Rahmen liegenden Dockhand-Endpunkte (282/318) haben ein MCP-Tool — siehe docs/coverage.md für die vollständige, automatisch aktualisierte Aufschlüsselung nach Bereich.

Dockhand ist ein Docker-Verwaltungsserver, der über Hawser-Agenten eine Verbindung zu mehreren Docker-Hosts herstellt. Dieser MCP-Server bietet vollständigen programmatischen Zugriff auf alle Dockhand-Funktionen.

Funktionen

• 280+ MCP-Tools für die Dockhand-API — siehe docs/coverage.md für die genaue, automatisch aktualisierte Abdeckung

• Streamable-HTTP-Transport (MCP-Spezifikation 2025-03-26) für das Hosten in Docker-Containern

• Sitzungsbasierte Authentifizierung mit automatischem Relogin bei 401

• SSE-Unterstützung für Deploy-Operationen (start, stop, down, restart)

• Umgebungsfilter, erzwungen für alle Container-/Stack-/Image-/Netzwerk-/Volume-Endpunkte

• Docker-bereit mit mehrstufigem Build, Nicht-Root-Benutzer und Health Checks

Related MCP server: dockhand-mcp

Schnellstart

Docker (empfohlen)

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

Aus dem Quellcode

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

Konfiguration

Sichern des Transports

/mcp bindet standardmäßig an 0.0.0.0:8080 (siehe MCP_HOST oben) und akzeptiert ohne Konfiguration — wenn weder MCP_ALLOWED_HOSTS, MCP_ALLOWED_ORIGINS noch MCP_AUTH_TOKEN gesetzt sind — jede Anfrage ohne Host-/Origin-Prüfung und ohne Authentifizierung. Dies ist dasselbe Verhalten, das mcp-dockhand schon immer hatte, und wurde bewusst als Standard beibehalten: Wenn eine Prüfung standardmäßig aktiviert wäre, würden Anfragen von jedem Client abgelehnt, der den Server nicht als localhost/127.0.0.1 erreicht (eine LAN-IP, ein Reverse-Proxy, ein Docker-Netzwerk-Alias), was bestehende Bereitstellungen bei einem routinemäßigen Update beschädigen würde.

Sie sollten dies aktivieren, sobald /mcp über die Loopback-Schnittstelle Ihrer eigenen Maschine hinaus erreichbar ist — der Server verfügt über eine Dockhand-Admin-Anmeldeinformation, und jeder Tool-Aufruf handelt mit dieser Identität, sodass jeder, der eine MCP-Sitzung öffnen kann, Docker kontrolliert (Container-Exec, Host-Bind-Mounts über create_container, Datei-Lesen/-Schreiben, gespeicherte Git-Anmeldedaten). Wenn kein Schutz konfiguriert ist, protokolliert der Server beim Start eine [security] WARNING als Erinnerung. Drei unabhängige, alle optional aktivierbare Ebenen sind verfügbar:

1. Host-Allowlist (MCP_ALLOWED_HOSTS). Sobald sie auf einen nicht-leeren Wert gesetzt ist, wird jede Anfrage an /mcp – POST, GET und DELETE – mit 403 abgelehnt, sofern ihr Host-Header nicht der Allowlist entspricht. Dies ist die primäre Verteidigung gegen DNS-Rebinding: Eine bösartige Webseite kann den Browser des Betreibers nicht dazu bringen, den Server unter einem Host-Wert zu erreichen, den die Allowlist akzeptiert. Setzen Sie sie darauf, wie Ihr Client den Server tatsächlich erreicht – localhost:8080/127.0.0.1:8080 für das dokumentierte lokale Setup, oder, wenn Sie sich direkt über eine Adresse statt über localhost verbinden (einschließlich des weiter unten beschriebenen mcp-proxy-Fernserver-Setups), auf das exakte host:port, das Ihr Client sendet, z. B. 100.100.50.40:8222. Wenn Sie das falsch einstellen, wird jede Anfrage mit 403 Invalid Host header abgelehnt – prüfen Sie die Meldung, sie gibt den erkannten Host-Wert wieder.

2. Origin-Allowlist (MCP_ALLOWED_ORIGINS). Sobald gesetzt, wird jede Anfrage, die doch einen Origin-Header sendet, der nicht in der Liste steht, mit 403 abgelehnt. Ein fehlender Origin-Header wird immer durchgelassen (der eigene MCP-Client des SDKs und die meisten Nicht-Browser-Tools senden keinen), daher ist dies nur nützlich, wenn ein browserbasierter Client direkt mit /mcp kommuniziert; die Host-Allowlist oben ist es, die DNS-Rebinding tatsächlich stoppt.

3. Bearer-Token (MCP_AUTH_TOKEN). Sobald gesetzt, muss jede /mcp-Anfrage Authorization: Bearer <token> enthalten, andernfalls wird sie mit 401 abgelehnt; der Vergleich erfolgt in konstanter Zeit. Empfohlen zusammen mit der Host-Allowlist für jede Bereitstellung, die von mehr als nur dem eigenen Rechner des Betreibers aus erreichbar ist.

# .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`>

Absichern des Servers mit CrowdSec

Der Server schreibt für jede Anfrage eine Zugriffszeile im nginx-Format nach stdout, einschließlich der abgelehnten, während das strukturierte Anwendungsprotokoll nach stderr geht. CrowdSec parst die Zugriffszeilen mit seinen Standard-Kollektionen – kein benutzerdefinierter Parser erforderlich.

Fügen Sie auf dem Host, auf dem Ihr CrowdSec-Agent läuft, eine Akquisitionsdatei hinzu:

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

Beide Labels sind erforderlich, und keines von beiden meldet sich lautstark, wenn man es vergisst. type: docker aktiviert crowdsecurity/docker-logs, das den JSON-Envelope von Docker entpackt. program: nginx-mcp aktiviert crowdsecurity/nginx-logs, das auf program mit Präfix nginx abgleicht – das Suffix -mcp hält diese Quelle von Ihren anderen nginx-Quellen unterscheidbar. Fehlt ein Label, erzeugt die Kette schlicht nichts, und nichts meldet es.

Nach der Einrichtung greifen die Standard-Szenarien:

Eine 403 ist ebenfalls beachtenswert: Sie bedeutet, dass eine Anfrage die MCP_ALLOWED_HOSTS- oder MCP_ALLOWED_ORIGINS-Prüfung nicht bestanden hat, was aus dieser Perspektive wie ein DNS-Rebinding-Versuch aussieht.

Das Standard-401-Szenario zählt nur POST. Sein Filter ist evt.Parsed.verb == 'POST' – ein Literal, keine Liste. Dieser Server bedient POST, GET und DELETE auf /mcp, und die Bearer-Prüfung läuft allen dreien voraus, sodass ein falsches Token auf GET /mcp oder DELETE /mcp genauso 401 zurückgibt wie bei POST – und LePresidente/http-generic-401-bf zählt diese nie. Jemand, der MCP_AUTH_TOKEN über GET /mcp errät, ist dafür unsichtbar.

Dies ist eine Eigenschaft des Upstream-Szenarios, die jede nginx-Bereitstellung teilt, die es verwendet – nicht etwas, das das Protokollformat dieses Servers beheben kann. Um das zu schließen, fügen Sie ein lokales Szenario hinzu, das den verb-Filter entfernt oder die drei Methoden abgleicht, die dieser Server beantwortet. Behandeln Sie die obige Zeile bis dahin als „wiederholte 401 auf POST /mcp“.

Setzen Sie TRUSTED_PROXIES, bevor Sie dies aktivieren. Hinter einem Reverse-Proxy kommt jede Anfrage von der Adresse des Proxys. Ohne TRUSTED_PROXIES wird diese Adresse protokolliert – der erste von CrowdSec ausgesprochene Bann nimmt also den Proxy mit aus dem Verkehr und damit jeden Benutzer dahinter. Setzen Sie sie auf die Adresse oder das Subnetz, aus dem Ihr Proxy spricht.

Die Einstellung ist auch in die andere Richtung bewusst gewählt: Die Weiterleitungs-Header werden nur von einem Peer auf dieser Liste akzeptiert. Ihnen bedingungslos zu vertrauen, würde es jedem direkten Aufrufer erlauben, einen beliebigen Dritten zu benennen und dessen Sperrung zu veranlassen.

Eine erwartete Nebenwirkung: Die strukturierten JSON-Zeilen teilen sich den Container-Logstream und tragen dasselbe program-Label, sodass sie das nginx-Muster nicht erfüllen und in cscli metrics als unparsed zählen. Das ist Rauschen, kein Fehler – kein Alarm, keine Entscheidung.

MCP-Client-Konfiguration

Claude Desktop / Claude Code

Fügen Sie zu Ihren MCP-Einstellungen hinzu:

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

Wenn der Server ein Bearer-Token erzwingt (MCP_AUTH_TOKEN gesetzt – siehe Sichern des Transports), muss der Client es als Authorization-Header senden, andernfalls wird jede Anfrage mit 401 abgelehnt. In der .mcp.json von Claude Code fügen Sie einen headers-Block hinzu – referenzieren Sie eine Umgebungsvariable, damit das Token nie in der (oft versionsverwalteten) Konfigurationsdatei lebt:

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

Senden Sie das Token nur über einen verschlüsselten Transport. Ein Bearer-Token über unverschlüsseltes http:// in einem gemeinsamen Netzwerk kann mitgelesen werden – beenden Sie TLS an einem Reverse-Proxy oder erreichen Sie den Server über eine WireGuard/Tailscale/VPN-Verbindung (das HTTP auf Anwendungsebene wird dann vom Tunnel verschlüsselt).

Exportieren Sie DOCKHAND_MCP_TOKEN in der Umgebung, aus der Claude Code gestartet wird (z. B. aus einer gitignorieten .env, die Sie vor dem Start sourcen). Der Host/das host:port, mit dem Sie sich verbinden, muss außerdem in MCP_ALLOWED_HOSTS des Servers stehen, falls diese Allowlist gesetzt ist. Für Claude Desktop (die native Konfiguration hat kein headers-Feld) übergeben Sie das Token über die mcp-proxy-Lösung unten – mcp-proxy leitet einen Authorization-Header über seine eigene Umgebung/Argumente weiter.

Claude Desktop mit einem entfernten Server (mcp-proxy)

Claude Desktop kann mit der nativen "url"-Konfiguration oben keine Verbindung zu einem entfernten mcp-dockhand-Server (nicht localhost) herstellen, selbst wenn der Endpunkt selbst erreichbar ist. Das Symptom ist ein allgemeiner "not a valid MCP server"-Fehler in Claude Desktop, während eine einfache Browser-/curl-Anfrage an dieselbe URL korrekt {"error":"Invalid or missing session ID"} zurückgibt. Dies ist eine bekannte Einschränkung von Claude Desktop mit entfernten Streamable-HTTP-Servern, kein mcp-dockhand-Fehler.

Lösung: Wickeln Sie die Verbindung mit mcp-proxy, das Streamable HTTP in stdio übersetzt – einen Transport, den Claude Desktop zuverlässig verarbeitet:

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

Alle Tools laden und funktionieren über den Proxy korrekt. Dank an @deadrubberboy für die Meldung und das Teilen der Lösung (#90).

Tool-Referenz

Container (27 Tools)

Stacks (21 Tools)

Images (9)

Umgebungen (18)

Netzwerke (7)

Volumes (9 Tools)

Git-Stacks (15 Tools)

Dashboard & Aktivität (8 Tools)

Auth & Hawser (12 Tools)

Audit (4 Tools)

Benachrichtigungen (8 Tools)

Registries (10 Tools)

System & Einstellungen (19 Tools)

Benutzer, Rollen & Einstellungen (20 Tools)

Zeitpläne (9 Tools)

Auto-Update (3 Tools)

Selbsthilfe-/Meta-Tools (6 Tools)

Diagnose für diesen MCP-Server selbst, abweichend von den Dockhand-API-Tools oben — nützlich für einen Client oder Betreiber, der fragt: „Ist dieser Server gesund und korrekt konfiguriert?" und nicht „Ist Dockhand gesund?". Keines dieser sechs Tools akzeptiert Eingabeargumente, und keines kapselt einen einzelnen Dockhand-Endpunkt wie die Tabellen oben (get_tool_manifest und get_runtime_stats rufen überhaupt keinen Dockhand-Endpunkt auf) — siehe src/tools/meta.ts.

Hinweise:

• check_for_update benötigt ausgehenden Netzwerkzugriff auf api.github.com (die Releases-API von GitHub) — es degradiert zu updateAvailable: null, anstatt zu scheitern, falls diese nicht erreichbar ist.

• Kein Meta-Tool legt einen geheimen Wert offen. validate_config meldet nur, ob die erforderlichen Umgebungsvariablen vorhanden sind (boolesche Werte) und ob sie authentifizieren (ein boolescher Wert + der rohe HTTP-Statuscode, z. B. 200/401) — niemals die Anmeldedatenwerte selbst. self_check meldet die Gültigkeit der Authentifizierung auf dieselbe Weise. lastError von get_runtime_stats enthält nur einen Toolnamen, eine Fehlermeldung und einen Zeitstempel — niemals Aufrufargumente oder Antwort-Payloads. Diese Fehlermeldung ist jedoch nicht vollständig undurchsichtig: Bei einem fehlgeschlagenen Dockhand-API-Aufruf kann sie einen Ausschnitt des vorgelagerten HTTP-Status und des Antworttexts einbetten (über die eigene Dockhand API error: ... returned <status>: <body>-Meldung von DockhandClient), und sie wird an denjenigen MCP-Client zurückgegeben, der als Nächstes get_runtime_stats aufruft — nicht unbedingt an den, der den ursprünglichen Fehler ausgelöst hat. Sie enthält niemals Anfragetexte oder Anmeldedatenwerte und wird auf 500 Zeichen gekürzt (mit einem Auslassungszeichen), bevor sie gespeichert wird, sodass eine übermäßig große vorgelagerte Antwort niemals vollständig zurückgegeben wird.

Wichtige Hinweise

update_stack_env — Zusammenführen- vs. Ersetzen-Semantik

Der Dockhand-REST-Endpunkt PUT /api/stacks/{name}/env hat Ersetzen-Semantik: Das Übermitteln einer partiellen Variablenliste löscht stillschweigend alle anderen Variablen aus dem Stack. Ein Update einer einzelnen Variablen würde alles andere löschen.

Um versehentlichen Datenverlust zu verhindern, verwendet dieses MCP-Tool standardmäßig den Zusammenführen-Modus:

1. Es ruft die aktuelle Variablenliste über GET /api/stacks/{name}/env ab.

2. Es führt die eingehenden Variablen nach Schlüssel zusammen (neue Werte überschreiben vorhandene bei Schlüsselkollision).

3. Es schreibt die vollständige kombinierte Liste über PUT zurück.

# 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")

Verwenden Sie mode="replace" nur, wenn Sie die gesamte Variablengruppe absichtlich ersetzen möchten.

Umgebungs-ID ist erforderlich

Die meisten Docker-Ressourcen-Endpunkte (Container, Stacks, Images, Netzwerke, Volumes) erfordern einen Parameter environmentId. Dieser wird auf den Abfrageparameter ?env=<id> in der Dockhand-API abgebildet. Ohne ihn geben die Endpunkte leere Arrays zurück.

SSE-Antworten

Bereitstellungsvorgänge (start, stop, down, restart, compose update with restart) geben Server-Sent Events zurück. Der MCP-Server parst diese automatisch und gibt das Endergebnis zurück.

Authentifizierung

Der Server verwendet sitzungsbasierte Cookie-Authentifizierung. Er:

• Meldet sich bei der ersten Anfrage an

• Speichert das Sitzungscookie im Speicher

• Authentifiziert sich bei 401-Antworten erneut

• Behandelt Sitzungszeitüberschreitung (24h)

Fehlerbehebung

Beginnen Sie mit LOG_LEVEL=debug. Jede Dockhand-Anfrage erscheint dann mit ihrem Endpunkt, Statuscode und ihrer Dauer, und jede Zeile eines einzelnen Aufrufs teilt sich eine call-Kennung — greppen Sie danach, um die gesamte Sequenz zu erhalten. Die req-Kennung verbindet diese Zeilen mit der Zugriffszeile, die sie ausgelöst hat, und sid umfasst alles, was ein Client während seiner gesamten Sitzung getan hat. Bei Anfragen über den Client ist ms die vollständige Anfragedauer — sie umfasst das Lesen des Antworttexts, nicht nur die Zeit bis zum Eintreffen der Antwortheader, sodass sie widerspiegelt, was eine langsame oder stockende gestreamte Antwort (z. B. die SSE-Ausgabe einer Bereitstellung) tatsächlich gekostet hat — und bytes ist die Größe des tatsächlich gelesenen Texts. (Die Anmelde- und Selbstprüf-Sonden bootstrappen den Client und können nicht über ihn geleitet werden, daher protokollieren ihre Zeilen die Zeit bis zu den Headern ohne ein bytes-Feld.) Eine fehlgeschlagene Dockhand-Anfrage protokolliert zusätzlich eine warn-Zeile mit errType — dem Ausnahmenamen (z. B. TimeoutError, TypeError), einem begrenzten Vokabular statt freiem Text — sodass Sie Fehler nach Fehlertyp filtern können. Diese Warnzeile wird sowohl ausgelöst, wenn die Anfrage selbst fehlschlug, bevor eine Antwort eintraf, als auch, wenn das Lesen eines Antworttexts teilweise fehlschlug (z. B. ein SSE-Stream, der mitten im Stream sein Timeout erreicht) — in beiden Fällen spiegelt ms wider, wie lange es gedauert hat, bis der Fehler auftrat.

Entwicklung

# 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 lintet src/ und tests/ mit zwei Regeln: no-unused-vars und no-explicit-any. Da typescript-eslint den festgepinnten typescript@^7.0.2-Compiler nicht unterstützt — es wirft bei TS 7.0 einen harten Fehler, nicht nur eine Peer-Warnung: siehe typescript-eslint#10940 — läuft das Linting in einem Wegwerf-node:22-Container mit festgepinntem TypeScript 5 (die Sprache ist über TS 5/6/7 identisch; nur der Compiler unterscheidet sich). Es mountet src/, tests/ und eslint.config.js schreibgeschützt, daher ist Docker erforderlich, um es auszuführen. Dasselbe Skript läuft als harte Hürde in CI. Ungenutzte Importe/Lokale werden zusätzlich nativ auf TS 7 von tsc erkannt (noUnusedLocals/noUnusedParameters in tsconfig.tests.json, über npm run typecheck:tests).

Lizenz

MIT