dockhand-mcp

MCP (Model Context Protocol) sidecar server for Dockhand (GitHub). Exposes Dockhand's container, image, volume, network, and stack management as MCP tools over Streamable HTTP, so MCP clients (Claude Desktop, Claude Code, etc.) can manage Docker resources through Dockhand.

This is a standalone service — it does not modify Dockhand itself, and calls Dockhand's existing REST API using a Dockhand API token.

Configuration

| Var | Required | Description | |---|---|---| | DOCKHAND_URL | yes | Base URL of the Dockhand instance, e.g. http://dockhand:3000 | | DOCKHAND_API_TOKEN | one of these two | Dockhand API token (create one in Dockhand under Profile → API tokens) | | DOCKHAND_API_TOKEN_FILE | one of these two | Path to a file/Docker secret containing the token | | MCP_AUTH_TOKEN | yes | Shared secret required by MCP clients calling this sidecar | | MCP_ALLOWED_HOSTS | no | Comma-separated list of exact hostnames to allow via DNS-rebinding host-header validation. Unset by default — no host filtering is applied, and MCP_AUTH_TOKEN remains the primary access-control gate. | | DOCKHAND_MCP_READONLY | no (default false) | Set true to only register read/list/inspect tools | | DOCKHAND_MCP_ENABLE_BACKUPS | no (default false) | Set true to register backup config/snapshot tools | | DOCKHAND_MCP_ENABLE_USERS | no (default false) | Set true to register user and role tools | | DOCKHAND_MCP_ENABLE_REGISTRIES | no (default false) | Set true to register the registry listing tool | | DOCKHAND_MCP_ENABLE_VULNERABILITIES | no (default false) | Set true to register vulnerability listing and scan tools | | DOCKHAND_MCP_ENABLE_GIT | no (default false) | Set true to register git-backed stack tools | | DOCKHAND_MCP_ENABLE_SCHEDULES | no (default false) | Set true to register schedule tools | | DOCKHAND_MCP_ENABLE_EXEC | no (default false) | Set true to register the exec_container tool (runs commands inside containers — effectively remote code execution, so off by default) | | PORT | no (default 8787) | Port the MCP endpoint listens on |

Running

docker build -t dockhand-mcp .
docker run -p 8787:8787 \
  -e DOCKHAND_URL=http://dockhand:3000 \
  -e DOCKHAND_API_TOKEN=dh_... \
  -e MCP_AUTH_TOKEN=... \
  dockhand-mcp

See docker-compose.example.yaml for running alongside Dockhand itself.

On startup, the sidecar checks connectivity to DOCKHAND_URL by calling GET /api/environments and logs the result, along with the minimum supported Dockhand version. A failed check is logged as an error but does not prevent the server from starting — Dockhand may simply not be ready yet — so tool calls will fail individually with clear errors until Dockhand is reachable. Dockhand does not expose its own app version through a REST endpoint, so the minimum-version notice is informational rather than actively enforced.

MCP endpoint

POST /mcp — Streamable HTTP MCP endpoint. Requires Authorization: Bearer <MCP_AUTH_TOKEN>.

GET /health — unauthenticated liveness check.

Client configuration

Example .mcp.json for Claude Code (or ~/.claude.json for a user-scoped config), pointing at a deployed sidecar:

{
  "mcpServers": {
    "dockhand-mcp": {
      "type": "http",
      "url": "https://dockhand-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      }
    }
  }
}

Equivalent CLI command:

claude mcp add dockhand-mcp --transport http https://dockhand-mcp.example.com/mcp --header "Authorization: Bearer ${MCP_AUTH_TOKEN}"

${MCP_AUTH_TOKEN} expands from the environment Claude Code runs in — set it to the same value configured on the sidecar, rather than hardcoding the token in the config file.

Tools

Every tool except list_environments, list_users, get_user, list_roles, list_registries, and list_schedules requires an environmentId (or an id scoped to a specific stored resource) — call list_environments first to discover valid environment IDs.

Mutating tools are also disabled whenever DOCKHAND_MCP_READONLY=true, regardless of the domain toggle below.

Core (always registered — no toggle required)

| Tool | Type | Description | |---|---|---| | list_environments | Read-only | List all Dockhand environments (Docker hosts). Call this first to discover valid environmentId values for other tools. | | list_containers | Read-only | List containers in a Dockhand environment. | | get_container | Read-only | Get full inspect details for a single container. | | get_container_logs | Read-only | Get recent logs for a container. | | list_images | Read-only | List images in a Dockhand environment. | | list_volumes | Read-only | List volumes in a Dockhand environment. | | list_networks | Read-only | List networks in a Dockhand environment. | | list_stacks | Read-only | List Compose stacks in a Dockhand environment. | | get_stack_env | Read-only | Get all environment variables for a stack (merged view of the .env file and stored secrets). Secret values are masked as ***. | | get_stack_env_file | Read-only | Get the raw .env file content for a stack, as-is (comments and formatting preserved). Non-secret variables only. | | get_container_stats | Read-only | Get a one-shot CPU, memory, network and block-IO stats snapshot for a container. | | get_container_top | Read-only | List the processes running inside a container. | | list_pending_updates | Read-only | List containers that have a newer image available, from the last update check. | | check_container_updates | Mutating | Check all containers in an environment for newer images. Returns a jobId — poll with get_container_update_check_status. | | get_container_update_check_status | Read-only | Check the status of an update check started by check_container_updates. | | cancel_container_update_check | Mutating | Cancel a running update check. | | update_container | Mutating | Recreate a container with a newer image, preserving its configuration. Blocks until done. | | batch_update_containers | Mutating | Recreate several containers with their latest images. Blocks until done. | | start_container | Mutating | Start a stopped container. | | stop_container | Mutating | Stop a running container. | | restart_container | Mutating | Restart a container. | | pause_container | Mutating | Pause all processes in a running container. | | unpause_container | Mutating | Resume all processes in a paused container. | | rename_container | Mutating | Rename a container (also updates its auto-update schedule). | | remove_container | Mutating | Remove (delete) a container. | | pull_image | Mutating | Pull an image from a registry. Returns immediately with a jobId — poll with get_image_pull_status. | | get_image_pull_status | Read-only | Check the status of an image pull started by pull_image. | | cancel_image_pull | Mutating | Cancel a running image pull started by pull_image. | | remove_image | Mutating | Remove (delete) an image. | | remove_volume | Mutating | Remove (delete) a volume. | | deploy_stack | Mutating | Deploy (up) a Compose stack. Returns immediately with a jobId — poll with get_stack_deploy_status. | | get_stack_deploy_status | Read-only | Check the status of a stack deploy started by deploy_stack. | | cancel_stack_deploy | Mutating | Cancel a running stack deploy started by deploy_stack. | | down_stack | Mutating | Take a Compose stack down (docker compose down) — stops and removes its containers. Returns immediately with a jobId — poll with get_stack_down_status. | | get_stack_down_status | Read-only | Check the status of a stack down started by down_stack. | | cancel_stack_down | Mutating | Cancel a running stack down started by down_stack. | | start_stack | Mutating | Start a stopped Compose stack. Returns immediately with a jobId — poll with get_stack_lifecycle_status. | | stop_stack | Mutating | Stop a Compose stack (docker compose stop), keeping its containers. Returns a jobId — poll with get_stack_lifecycle_status. | | restart_stack | Mutating | Restart a Compose stack, optionally with mode restart (default), ordered or recreate. Returns a jobId — poll with get_stack_lifecycle_status. | | get_stack_lifecycle_status | Read-only | Check the status of a stack start, stop or restart. | | cancel_stack_lifecycle | Mutating | Cancel a running stack start, stop or restart. | | set_stack_secret | Mutating | Save secret environment variables for a stack. Pass value "***" for a variable to keep its existing secret unchanged. | | set_stack_env_file | Mutating | Overwrite the raw .env file content for a stack. Replaces the entire file; empty content deletes it. |

Extended (each domain off by default — set its toggle to true to enable)

| Domain | Toggle | Status | Tool | Type | Description | |---|---|---|---|---|---| | Backups | DOCKHAND_MCP_ENABLE_BACKUPS | disabled by default | list_backup_configs | Read-only | List configured backups (stack or volume backup jobs) in Dockhand. | | Backups | DOCKHAND_MCP_ENABLE_BACKUPS | disabled by default | list_snapshots | Read-only | List backup snapshots, optionally scoped to a single backup config. | | Backups | DOCKHAND_MCP_ENABLE_BACKUPS | disabled by default | run_backup_config | Mutating | Manually trigger a backup config to run now. Returns immediately with a jobId — poll with get_backup_run_status. | | Backups | DOCKHAND_MCP_ENABLE_BACKUPS | disabled by default | get_backup_run_status | Read-only | Check the status of a backup run started by run_backup_config. | | Backups | DOCKHAND_MCP_ENABLE_BACKUPS | disabled by default | cancel_backup_run | Mutating | Cancel a running backup started by run_backup_config. | | Users/Roles | DOCKHAND_MCP_ENABLE_USERS | disabled by default | list_users | Read-only | List all Dockhand users. | | Users/Roles | DOCKHAND_MCP_ENABLE_USERS | disabled by default | get_user | Read-only | Get details for a single Dockhand user. | | Users/Roles | DOCKHAND_MCP_ENABLE_USERS | disabled by default | list_roles | Read-only | List all Dockhand roles. Requires an Enterprise license (returns an error on free-tier instances with auth enabled). | | Registries | DOCKHAND_MCP_ENABLE_REGISTRIES | disabled by default | list_registries | Read-only | List configured container registries in Dockhand. Credentials are never included — only a hasCredentials flag. | | Vulnerabilities | DOCKHAND_MCP_ENABLE_VULNERABILITIES | disabled by default | list_vulnerabilities | Read-only | List aggregated vulnerability findings for an environment, with optional filtering and pagination. | | Vulnerabilities | DOCKHAND_MCP_ENABLE_VULNERABILITIES | disabled by default | scan_all_vulnerabilities | Mutating | Scan every image in an environment for vulnerabilities. Returns immediately with a jobId — poll with get_vulnerability_scan_status. | | Vulnerabilities | DOCKHAND_MCP_ENABLE_VULNERABILITIES | disabled by default | get_vulnerability_scan_status | Read-only | Check the status of a vulnerability scan started by scan_all_vulnerabilities. | | Vulnerabilities | DOCKHAND_MCP_ENABLE_VULNERABILITIES | disabled by default | cancel_vulnerability_scan | Mutating | Cancel a running vulnerability scan started by scan_all_vulnerabilities. | | Git deploy | DOCKHAND_MCP_ENABLE_GIT | disabled by default | list_git_stacks | Read-only | List git-backed Compose stacks in Dockhand. | | Git deploy | DOCKHAND_MCP_ENABLE_GIT | disabled by default | sync_git_stack | Mutating | Pull the latest commit for a git-backed stack from its remote, without redeploying. | | Git deploy | DOCKHAND_MCP_ENABLE_GIT | disabled by default | deploy_git_stack | Mutating | Sync and redeploy a git-backed stack. Ret