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 endpointsStreamable HTTP Transport (MCP Spec 2025-03-26) for Docker container hostingSession-based Auth with auto-relogin on 401SSE Support for deploy operations (start, stop, down, restart)Environment Filter enforced on all container/stack/image/network/volume endpointsDocker Ready with multi-stage build, non-root user, and health checks
Quick Start
Docker (recommended)
hljs language-bash
Copy 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
hljs language-yaml
Copy 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
hljs language-bash
Copy 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
Variable Required Default Description DOCKHAND_URLYes - Dockhand server URL DOCKHAND_USERNAMEYes - Dockhand username DOCKHAND_PASSWORDYes - Dockhand password MCP_PORTNo 8080Port for the MCP server LOG_LEVELNo infoLog level
MCP Client Configuration
Claude Desktop / Claude Code
Add to your MCP settings:
hljs language-json
Copy {
"mcpServers" : {
"dockhand" : {
"url" : "http://localhost:8080/mcp"
}
}
}
Tool Reference
Containers (27 tools)
Tool Description list_containersList all containers in an environment get_containerGet container details inspect_containerDocker inspect (full details) get_container_logsGet container logs get_container_statsGet resource usage stats get_container_topGet running processes start_containerStart a container stop_containerStop a container restart_containerRestart a container pause_containerPause a container unpause_containerUnpause a container rename_containerRename a container update_containerUpdate container settings create_containerCreate a new container get_container_shellsList available shells list_container_filesBrowse files inside container get_container_file_contentRead file from container create_container_fileCreate file in container delete_container_fileDelete file in container rename_container_fileRename file in container chmod_container_fileChange file permissions check_container_updatesCheck for image updates get_pending_updatesGet pending updates batch_update_containersBatch update containers get_container_sizesGet container disk sizes get_containers_statsGet aggregated stats
Stacks (21 tools)
Tool Description list_stacksList all stacks get_stackGet stack details create_stackCreate and optionally deploy a stack start_stackStart a stack (compose up) stop_stackStop a stack (compose stop) restart_stackRestart a stack down_stackTake down a stack (compose down) delete_stackDelete a stack get_stack_composeRead compose file update_stack_composeUpdate compose file get_stack_envRead environment variables update_stack_envUpdate environment variables get_stack_env_rawRead raw .env file validate_stack_envValidate env variables scan_stacksScan filesystem for stacks adopt_stackAdopt an untracked stack relocate_stackMove stack to new path get_stack_sourcesGet stack sources get_stack_base_pathGet base path get_stack_path_hintsGet path suggestions validate_stack_pathValidate a stack path
Images (9 tools)
Tool Description list_imagesList all images get_imageGet image details get_image_historyGet image layer history tag_imageTag an image remove_imageRemove an image pull_imagePull an image push_imagePush an image scan_imageVulnerability scan (Trivy/Grype) export_imageExport image as tarball
Environments (18 tools)
Tool Description list_environmentsList all environments get_environmentGet environment details create_environmentCreate an environment update_environmentUpdate an environment delete_environmentDelete an environment test_environmentTest connection test_environment_connectionTest without saving detect_docker_socketAuto-detect socket get_environment_timezoneGet timezone set_environment_timezoneSet timezone get_environment_update_checkGet update-check settings set_environment_update_checkSet update-check settings get_environment_image_pruneGet image prune settings set_environment_image_pruneSet image prune settings list_environment_notificationsList notifications create_environment_notificationCreate notification get_environment_notificationGet notification delete_environment_notificationDelete notification
Networks (7 tools)
Tool Description list_networksList all networks get_networkGet network details inspect_networkInspect network create_networkCreate a network remove_networkRemove a network connect_container_to_networkConnect container disconnect_container_from_networkDisconnect container
Volumes (9 tools)
Tool Description list_volumesList all volumes get_volumeGet volume details inspect_volumeInspect volume browse_volumeBrowse files in volume get_volume_file_contentRead file from volume release_volume_browseRelease browse session clone_volumeClone a volume export_volumeExport volume remove_volumeRemove volume (destructive)
Git Stacks (15 tools)
Tool Description list_git_stacksList Git-based stacks get_git_stackGet Git stack details deploy_git_stackDeploy a Git stack (SSE) sync_git_stackSync with remote repo test_git_stackTest Git connection get_git_stack_env_filesGet env files trigger_git_webhookTrigger webhook get_git_webhookGet webhook details list_git_credentialsList Git credentials create_git_credentialCreate Git credential get_git_credentialGet credential details update_git_credentialUpdate credential delete_git_credentialDelete credential list_git_repositoriesList Git repositories create_git_repositoryCreate repository config
Dashboard & Activity (8 tools)
Tool Description get_dashboard_statsGet dashboard statistics get_dashboard_preferencesGet display preferences set_dashboard_preferencesSet display preferences get_activity_feedGet activity feed get_container_activityContainer activity get_activity_eventsActivity events get_activity_statsActivity statistics get_merged_logsMerged logs from containers
Auth & Hawser (12 tools)
Tool Description get_auth_sessionCheck session status get_auth_providersList auth providers get_auth_settingsGet auth settings create_oidc_providerCreate OIDC provider get_oidc_providerGet OIDC provider test_oidc_providerTest OIDC provider create_ldap_providerCreate LDAP provider get_ldap_providerGet LDAP provider test_ldap_providerTest LDAP provider list_hawser_tokensList Hawser tokens create_hawser_tokenCreate Hawser token revoke_hawser_tokenRevoke Hawser token
Audit (4 tools)
Tool Description get_audit_logGet audit log get_audit_eventsGet audit event types get_audit_usersAudit data by user export_audit_logExport audit log
Notifications (8 tools)
Tool Description list_notificationsList notifications create_notificationCreate notification get_notificationGet notification update_notificationUpdate notification delete_notificationDelete notification test_notificationTest notification test_notification_configTest without saving trigger_test_notificationTrigger test event
Registries (10 tools)
Tool Description list_registriesList registries create_registryAdd registry get_registryGet registry details update_registryUpdate registry delete_registryDelete registry set_default_registrySet as default search_registrySearch registry get_registry_catalogGet catalog get_registry_imageGet image from registry get_registry_tagsGet image tags
System & Settings (19 tools)
Tool Description health_checkServer health health_check_databaseDatabase health get_host_infoHost information get_system_infoSystem information get_system_diskDisk usage list_system_filesList system files get_system_file_contentRead system file get_changelogChangelog get_dependenciesDependencies get_general_settingsGeneral settings update_general_settingsUpdate settings get_theme_settingsTheme settings update_theme_settingsUpdate theme get_scanner_settingsScanner settings update_scanner_settingsUpdate scanner get_licenseLicense info activate_licenseActivate license get_prometheus_metricsPrometheus metrics prune_allPrune all resources
Users, Roles & Preferences (20 tools)
Tool Description list_usersList users create_userCreate user get_userGet user details update_userUpdate user delete_userDelete user get_user_mfa_statusMFA status enable_user_mfaEnable MFA disable_user_mfaDisable MFA get_user_rolesGet user roles set_user_rolesSet user roles list_rolesList roles create_roleCreate role get_roleGet role update_roleUpdate role delete_roleDelete role get_profileGet own profile update_profileUpdate own profile get_favoritesGet favorites set_favoritesSet favorites list_config_setsList config sets
Schedules (9 tools)
Tool Description list_schedulesList schedules get_schedule_settingsGet settings update_schedule_settingsUpdate settings get_schedule_executionsExecution history get_schedule_executionExecution details get_scheduleGet schedule run_schedule_nowRun immediately toggle_scheduleEnable/disable toggle_system_scheduleToggle system schedule
Auto-Update (3 tools)
Tool Description get_auto_update_settingsGet all auto-update settings get_container_auto_updateGet container auto-update set_container_auto_updateSet auto-update policy
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
hljs language-bash
Copy
npm install
npm run typecheck
npm run build
DOCKHAND_URL=https://your-server.com \
DOCKHAND_USERNAME=admin \
DOCKHAND_PASSWORD=secret \
npm run dev
License
MIT
@microsoft✓ Official