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

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