MCP Dockhand

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

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

• 130+ MCP Tools covering all Dockhand API endpoints
• 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

MCP Client Configuration

Claude Desktop / Claude Code

Add to your MCP settings:

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

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)

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)

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

License

MIT