Docker Manager MCP

# Docker Manager MCP [](https://github.com/jmagar/docker-mcp/pkgs/container/docker-mcp) [](https://github.com/jmagar/docker-mcp/actions/workflows/docker-build.yml) [](https://www.python.org/downloads/) [](https://github.com/jamesturk/fastmcp) [](https://opensource.org/licenses/MIT) **Control all your Docker hosts from one place.** Docker Manager MCP lets AI assistants manage containers, deploy stacks, and monitor services across your entire infrastructure - with zero configuration needed. ## 🚀 One-Line Install ```bash curl -sSL https://raw.githubusercontent.com/jmagar/docker-mcp/main/install.sh | bash ``` That's it! The installer: - ✅ Sets up SSH keys automatically - ✅ Imports all your existing hosts from SSH config - ✅ Configures secure authentication - ✅ Starts the service on port 8000 **No manual configuration needed.** If you can SSH to it, Docker Manager can control it. ## 🎯 What You Can Actually Do - **Deploy applications** across multiple Docker hosts - **Control containers** with start/stop/restart operations - **Monitor services** with real-time log streaming - **Manage stacks** using Docker Compose configurations - **Update services** without downtime using rolling updates - **Check port usage** to avoid conflicts - **Auto-discover hosts** from your SSH configuration ## 🛠 The 3 Tools **Simply talk to your AI assistant in plain English.** No complex commands or JSON needed - just describe what you want to do with your Docker infrastructure. ### Tool 1: `docker_hosts` Simplified Docker hosts management tool. **Actions:** • **list**: List all configured Docker hosts - Required: none • **add**: Add a new Docker host (auto-runs test_connection and discover) - Required: host_id, ssh_host, ssh_user - Optional: ssh_port (default: 22), ssh_key_path, description, tags, enabled (default: true) • **ports**: List or check port usage on a host - Required: host_id - Optional: port (for availability check) • **import_ssh**: Import hosts from SSH config (auto-runs test_connection and discover for each) - Required: none - Optional: ssh_config_path, selected_hosts • **cleanup**: Docker system cleanup operations - Required: host_id, cleanup_type - Valid cleanup_type: "check" | "safe" | "moderate" | "aggressive" • **test_connection**: Test host connectivity (also runs discover) - Required: host_id • **discover**: Discover paths and capabilities on hosts - Required: host_id (use 'all' to discover all hosts sequentially) - Discovers: compose_path, appdata_path - Single host: Fast discovery (5-15 seconds) - All hosts: Sequential discovery (30-60 seconds total) • **edit**: Modify host configuration - Required: host_id - Optional: ssh_host, ssh_user, ssh_port, ssh_key_path, description, tags, compose_path, appdata_path, enabled • **remove**: Remove host from configuration - Required: host_id • **disk_usage**: Read-only Docker disk usage summary (alias of cleanup check) - Required: host_id **Natural language examples:** ``` "Add a new Docker host called production-1 at 192.168.1.100 with user dockeruser" "Add host staging at 10.0.1.50 using SSH key ~/.ssh/staging_key" "List all my Docker hosts" "Check what ports are being used on production-1" "Import hosts from my SSH config" "Clean up Docker on production-1 using safe mode" "Test connection to staging-server" "Discover capabilities on all hosts" "Update the compose path for production-1 to /opt/stacks" "Remove the old-server host from my configuration" ``` ### Tool 2: `docker_container` Consolidated Docker container management tool. **Actions:** • **list**: List containers on a host - Required: host_id - Optional: all_containers, limit, offset • **info**: Get container information - Required: host_id, container_id • **start**: Start a container - Required: host_id, container_id - Optional: force, timeout • **stop**: Stop a container - Required: host_id, container_id - Optional: force, timeout • **restart**: Restart a container - Required: host_id, container_id - Optional: force, timeout • **remove**: Remove a container - Required: host_id, container_id - Optional: force • **logs**: Get container logs - Required: host_id, container_id - Optional: follow, lines • **pull**: Pull a container image onto a host - Required: host_id, image_name **Natural language examples:** ``` "List all containers on production-1" "Include stopped containers on staging" "Show info for the nginx container on production-1" "Start the wordpress container on production-1" "Force stop the mysql database on staging with a 30 second timeout" "Restart the web server container on production-1" "Remove the old cache container from staging" "Tail the last 200 lines of logs for api-server on production-1" "Pull the latest nginx image on production-1" ``` ### Tool 3: `docker_compose` Consolidated Docker Compose stack management tool. **Actions:** • **list**: List stacks on a host - Required: host_id • **view**: View the compose file for a stack - Required: host_id, stack_name • **deploy**: Deploy a stack - Required: host_id, stack_name, compose_content - Optional: environment, pull_images, recreate • **up/down/restart/build/pull**: Manage stack lifecycle - Required: host_id, stack_name - Optional: options • **ps**: Show stack services (status and ports) - Required: host_id, stack_name • **discover**: Discover compose paths on a host - Required: host_id • **logs**: Get stack logs - Required: host_id, stack_name - Optional: follow, lines, services (subset) • **migrate**: Migrate stack between hosts - Required: host_id, target_host_id, stack_name - Optional: remove_source, skip_stop_source, start_target, dry_run **Natural language examples:** ``` "List all stacks on production-1" "Deploy wordpress stack to production-1 with this compose file: <content>" "Deploy plex to media-server with DB_PASSWORD=secret123" "Bring up the wordpress stack on production-1" "Take down the old-app stack on staging" "Restart the plex stack on media-server" "Build the development stack on staging" "Discover compose files on production-1" "Show logs from the wordpress stack on production-1" "Stream live logs from plex stack on media-server" "Show last 200 lines from api-stack logs on staging" "Migrate wordpress from old-server to new-server" "Do a dry run migration of plex from server1 to server2" "Migrate database stack and remove it from the source after" ``` ## 🏗 Architecture: Why 3 Consolidated Tools? Docker Manager MCP uses the **Consolidated Action-Parameter Pattern** instead of 27 individual tools. This architectural choice provides: ### **Token Efficiency** - **2.6x more efficient**: Our 3 tools use ~5k tokens vs. 27 individual tools using ~9.7k tokens - **Better scaling**: Adding new actions to existing tools is more efficient than creating new tools - **Context savings**: Each tool adds ~400-500 tokens - consolidation reduces this multiplicatively ### **Complex Operation Support** Docker management requires sophisticated multi-step operations: - **Migration**: stop → verify → archive → transfer → deploy → validate - **Cleanup**: analyze → confirm → execute → verify - **Deployment**: validate → pull → configure → start → health-check ### **Hybrid Connection Model** Different operations need different approaches: - **Container operations**: Docker contexts (API over SSH tunnel) for efficiency - **Stack operations**: Direct SSH (filesystem access) for compose file management ### **Service Layer Benefits** - **Centralized validation**: Consistent input validation across all operations - **Error handling**: Uniform error reporting and recovery - **Resource management**: Connection pooling, context caching, and cleanup - **Business logic**: Complex orchestration that simple decorators can't handle *For technical details, see [`docs/consolidated-action-pattern.md`](docs/consolidated-action-pattern.md)* --- **🚀 Advanced Migration Features:** **Transfer Method:** - **Rsync**: Universal compatibility for all Docker environments with compression and delta transfers **Enhanced Safety Features:** - **Always stops containers by default** (must explicitly skip with `skip_stop_source: true` - NOT recommended) - **Verifies all containers are completely stopped** before archiving (prevents data corruption) - **Archive integrity verification** before transfer - **Filesystem sync delays** after container shutdown - **Reliable transfers** with rsync for data consistency ## 💡 Real-World Use Cases ### Deploy a WordPress Site ```yaml # compose_content for WordPress deployment version: '3.8' services: wordpress: image: wordpress:latest ports: - "80:80" environment: WORDPRESS_DB_HOST: db WORDPRESS_DB_PASSWORD: secret db: image: mysql:5.7 environment: MYSQL_ROOT_PASSWORD: secret volumes: - db_data:/var/lib/mysql volumes: db_data: ``` Use with: "Deploy wordpress stack to production-1 with this compose file" ### Monitor Multiple Hosts Simply ask your AI assistant: - "Show me all my Docker hosts" - "List all containers on each host" - "Show me the logs from nginx on production-1" - "Stream live logs from all my database containers" ### Emergency Container Management When things go wrong, just describe the problem: - "Force stop all containers on production-1" - "What's using port 80 on my staging server?" - "Restart all my web services" - "Show me what's currently running on production-1" ### Migrate Stack to New Host Perfect for hardware upgrades, load balancing, or moving to faster storage: 1. **Test the migration** (dry run): ``` "Do a dry run migration of wordpress from old-server to new-server" ``` 2. **Rsync Migration** (universal compatibility): - **ALWAYS stops containers by default** (safety first!) - **Verifies all containers are completely stopped** (prevents data corruption) - Waits for filesystem sync to ensure data consistency - Archives all volumes and data (excludes cache, logs, node_modules) - **Verifies archive integrity** before transfer - Transfers via rsync with compression - Updates paths for the target host - Deploys and starts on the target - Preserves all your data and configurations **The migration intelligently handles:** - Named Docker volumes and bind mounts - Compose configurations and environment variables - Path translation between different host structures - **Rsync transfer** with compression and delta synchronization - **Data consistency** through container stopping and verification ## 🔧 Configuration (Optional!) The beauty of Docker Manager MCP is that **you don't need to configure anything**. It automatically: - Discovers your Docker hosts from SSH config - Sets up secure connections - Manages authentication But if you want to customize: ### Add Custom Hosts Create `~/.docker-mcp/config/hosts.yml`: ```yaml hosts: # Production Docker Host production-server: hostname: 192.168.1.100 user: myuser description: "Production Docker server" compose_path: /opt/compose # Where to store compose files appdata_path: /opt/appdata # Container data directory # Staging Docker Host staging-server: hostname: 192.168.1.101 user: myuser description: "Staging Docker server" compose_path: /opt/compose # Where to store compose files appdata_path: /opt/appdata # Container data directory ``` ### Use Environment Variables ```bash FASTMCP_PORT=8080 # Change port LOG_LEVEL=DEBUG # More verbose logging FASTMCP_DATA_DIR=/var/lib/docker-mcp/data # Persist OAuth tokens & runtime data DOCKER_MCP_DATA_DIR=/var/lib/docker-mcp/data # Alias for tooling expecting DOCKER_MCP_* # OAuth Authentication (Optional but Recommended) FASTMCP_ENABLE_OAUTH=true # Enable OAuth support (defaults to off) FASTMCP_SERVER_AUTH=fastmcp.auth.GoogleProvider # Select Google OAuth provider FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=your-client-id # Google OAuth client ID FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=your-client-secret # Google OAuth client secret FASTMCP_SERVER_AUTH_GOOGLE_REDIRECT_PATH=/auth/callback # OAuth callback path # Or use any other FastMCP auth provider by specifying its import path ``` ### 🚀 Transfer Method **Rsync Transfer Features:** - **Universal Compatibility**: Works with any Linux Docker host - **Data Integrity**: File-level verification with checksums - **Incremental**: Delta sync with compression for efficiency - **Metadata**: Preserves permissions, timestamps, and ownership - **Reliable**: File-by-file transfer with retry capabilities - **Use Case**: All Docker environments, universal compatibility **Performance:** - **Large datasets**: Efficient delta transfers reduce bandwidth - **Small stacks**: Quick transfers with minimal overhead - **Database migrations**: Container stopping ensures data consistency ## 🐳 Docker Deployment Already included! The installer creates everything: ```bash # Check status cd ~/.docker-mcp && docker compose ps # View logs cd ~/.docker-mcp && docker compose logs # Update to latest cd ~/.docker-mcp && docker compose pull && docker compose up -d # Stop service cd ~/.docker-mcp && docker compose down ``` ## 🔒 Security Built-In - **SSH key authentication only** (no passwords) - **Dedicated SSH keys** for Docker Manager (isolated from your personal keys) - **Persistent data volume** (`FASTMCP_DATA_DIR`) to retain OAuth credentials and runtime state across restarts - **OAuth authentication support** (Google, GitHub, or any FastMCP provider) - **Identity verification** with `whoami` diagnostic tool - **Read-only mounts** for configuration - **Rate limiting** to prevent abuse - **Non-root container** execution - **Automatic security updates** via GitHub Actions ### OAuth Authentication Features When OAuth is enabled (set `FASTMCP_ENABLE_OAUTH=true` and provide `FASTMCP_SERVER_AUTH`): - **Dynamic provider loading** - Use Google, GitHub, or custom auth providers - **`whoami` tool** - Verify authenticated user identity and claims - **Secure token handling** - Built on FastMCP's robust auth framework - **Flexible configuration** - Environment-based setup for easy deployment ## 💻 For Developers ### Quick Dev Setup ```bash git clone https://github.com/jmagar/docker-mcp cd docker-mcp uv sync uv run docker-mcp ``` ### Format Code ```bash uv run ruff format . uv run ruff check . --fix ``` ## 📁 What's Inside ``` docker-mcp/ ├── docker_mcp/ # Main application │ ├── server.py # FastMCP server with 3 consolidated tools │ ├── core/ # Docker & SSH management │ ├── services/ # Business logic │ └── tools/ # Tool implementations ├── config/ # Example configurations ├── tests/ # Comprehensive test suite └── install.sh # One-line installer ``` ## 🆘 Need Help? ### Container won't start? Just ask your AI assistant: ``` "What's running on port 80 on my-server?" "Show me the logs from my-app container on my-server" "Why won't my nginx container start on production-1?" ``` ### Can't connect to a host? Let your AI assistant help troubleshoot: ``` "Test the connection to my staging server" "Import all hosts from my SSH config" "Add my new server at 192.168.1.100 to Docker Manager" ``` ### Something else? - Check logs: `~/.docker-mcp/data/logs/` - Debug mode: `LOG_LEVEL=DEBUG` - [Open an issue](https://github.com/jmagar/docker-mcp/issues) ## 🎉 Why Docker Manager MCP? - **Zero Configuration** - Works out of the box with your existing setup - **Universal Control** - Manage all your Docker hosts from one place - **AI-Friendly** - Built for LLMs to orchestrate your infrastructure - **Production Ready** - Rate limiting, error handling, and logging built-in - **Secure by Default** - SSH keys only, no passwords ever - **Always Up-to-Date** - Automatic updates via Docker ## 📄 License MIT - Use it however you want! ## 🚀 Get Started Now ```bash # Install in 10 seconds curl -sSL https://raw.githubusercontent.com/jmagar/docker-mcp/main/install.sh | bash # That's it! Start managing your Docker infrastructure ``` **Questions?** [Open an issue](https://github.com/jmagar/docker-mcp/issues) - we're here to help!