Which integrations are available for this server?

Provides tools for managing Docker resources such as containers, images, volumes, networks, and Compose stacks in a Dockhand environment. Provides tools for managing git-backed Compose stacks, including listing, syncing, and deploying them.

How do I use dockhand-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@dockhand-mcp List all containers in the production environment." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

dockhand-mcp

by craibo

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

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

Related MCP server: rarcane

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. Returns immediately with a jobId — poll with `get_git_deploy_status`. Check the `success` field in the final result once done — a failed deploy is reported there, not as a tool error.
Git deploy	`DOCKHAND_MCP_ENABLE_GIT`	disabled by default	`get_git_deploy_status`	Read-only	Check the status of a git stack deploy started by `deploy_git_stack`.
Git deploy	`DOCKHAND_MCP_ENABLE_GIT`	disabled by default	`cancel_git_deploy`	Mutating	Cancel a running git stack deploy started by `deploy_git_stack`.
Schedules	`DOCKHAND_MCP_ENABLE_SCHEDULES`	disabled by default	`list_schedules`	Read-only	List all active Dockhand schedules (container auto-updates, git stack syncs, backups, and system jobs). Execution `details` and `logs` are omitted unless `includeExecutionDetails` is `true`.
Schedules	`DOCKHAND_MCP_ENABLE_SCHEDULES`	disabled by default	`run_schedule`	Mutating	Manually trigger a schedule to run now.
Schedules	`DOCKHAND_MCP_ENABLE_SCHEDULES`	disabled by default	`toggle_schedule`	Mutating	Enable or disable a schedule. Flips its current enabled state — check the returned `enabled` field to see the new state.
Container exec	`DOCKHAND_MCP_ENABLE_EXEC`	disabled by default	`exec_container`	Mutating	Run a short, non-interactive command in a running container and return stdout, stderr and exit code. Never registered when `DOCKHAND_MCP_READONLY=true`.

To enable a domain, set its toggle to true in the sidecar's environment (see Configuration), e.g.:

docker run -p 8787:8787 \
  -e DOCKHAND_URL=http://dockhand:3000 \
  -e DOCKHAND_API_TOKEN=dh_... \
  -e MCP_AUTH_TOKEN=... \
  -e DOCKHAND_MCP_ENABLE_BACKUPS=true \
  -e DOCKHAND_MCP_ENABLE_GIT=true \
  dockhand-mcp

The extended domains intentionally wrap only a minimal slice of Dockhand's REST surface for each area (no user/role/registry/git-credential CRUD) — full CRUD for these domains is out of scope, consistent with the project's minimal, LLM-friendly tool surface.

Not yet implemented

The tools above cover a deliberately minimal slice of Dockhand's REST API (checked against the Dockhand v1.0.51 OpenAPI spec, static/openapi.json in Finsys/dockhand). These are the known gaps, roughly in priority order. They are candidates, not commitments.

Stacks

Deploy history (GET /stacks/{name}/deploys, /{runId}, /{runId}/log) — useful for debugging failed deploys
Read and write the compose file (/stacks/{name}/compose), validate a stack
Create, delete and adopt stacks; stack tags

Containers

Create a container, update-runtime, release notes for an update (/version-notes)
Clear pending-update records, streaming batch update (batch-update-stream)
Auto-update settings per container (/auto-update/{containerName})
File browser, compose view, live log and stats streams

Pruning and system

Prune images, containers, networks, volumes, or all (/prune/*) — destructive, would need its own toggle
System info and disk usage (/system, /system/disk), per-environment disk warnings

Images, volumes, networks, registries

Images: history, tag, push, load/export, scan a single image
Volumes: create, clone, browse, export
Networks: create, remove, connect, disconnect
Registries: search, tags, catalog, create/update/delete

Backups

Restore and restore preview, destinations (list, test, verify), snapshot browse/diff/delete, config create/update/delete

Git

Create/update/delete git stacks, repositories, credentials (would need secret redaction), env files, webhooks

Vulnerabilities

Counts and export (/vulnerabilities/count, /export)

Other

Environment management (create, update, test, delete), templates, schedule execution history and settings, /batch
User and role create/update/delete, MFA

Known caveats

MIN_DOCKHAND_VERSION (1.0.41) has not been re-verified against the newest tools — restart_stack with mode=ordered needs Dockhand 1.0.46 or later. Dockhand does not expose its version over the API, so this is not enforced at runtime.
exec_container is bounded to about 30s on remote (Hawser/TCP) environments and takes an argv array, not a shell string.
There is no automated check that tool paths still exist in Dockhand's OpenAPI spec; a spec-drift test would catch renamed or removed endpoints.

Development

npm install
npm run dev     # watch mode
npm test        # run tests
npm run build   # compile to dist/

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

SMI Aware Assistant AOAuth
com.smiaware.mcp
Remote MCP server exposing SMI Aware tools, resources, and skills over Streamable HTTP.
Social Media Search
401
MANDATE Credential Broker B
io.github.projetnanocorp
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Security
111
Superserve
io.github.superserve-ai
MCP server for Superserve sandboxes: create, exec, and manage Firecracker microVMs
Virtualization Code Execution
2417
Flowral AI ToolsOAuth
app.flowral.mcp
Streamable HTTP MCP server exposing planner flows, tasks, and squads.
Project Management Workplace & Productivity
1

Related MCP Servers

rancher-mcp
Cloud Platforms Developer Tools
Jasonrve
A
license
Not graded
quality
D
maintenance
A standalone MCP server that exposes Rancher-side tools, forwards Authorization headers or uses configured credentials, and supports HTTP and stdio transports.
Updated 3 months ago (2026-07-06 15:22 UTC)
MIT
rarcane
Virtualization Developer Tools
dinglebear-ai
A
license
Not graded
quality
A
maintenance
MCP server for managing Docker containers, images, networks, volumes, and Compose projects via Arcane, exposing a single 'arcane' tool for read/write operations over stdio or HTTP.
Updated 13 days ago (2026-10-01 05:56 UTC)
3
AGPL 3.0
dockhand-readonly-mcp
Virtualization Monitoring
cgfm
F
license
A
quality
B
maintenance
Read-only MCP adapter for the Dockhand REST API, enabling secure querying of container environments, networks, stacks, and runtime status via STDIO or authenticated HTTP.
Updated 2 months ago (2026-08-02 09:08 UTC)
8
1
-
mcp-dockhand
Cloud Platforms Virtualization
t1nk333r
A
license
Not graded
quality
B
maintenance
MCP server exposing the Dockhand API as MCP tools. Enables AI assistants to manage Docker infrastructure including containers, stacks, images, networks, and volumes across multiple hosts.
Updated 2 months ago (2026-08-23 20:14 UTC)
MIT

dockhand-mcp

Configuration

Running

MCP endpoint

Client configuration

Tools

Core (always registered — no toggle required)

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

Not yet implemented

Development

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

rancher-mcp

rarcane

dockhand-readonly-mcp

mcp-dockhand

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