Docker Manager MCP

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

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:

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:

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:

🏗 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

🚀 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

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:

Use Environment Variables

🚀 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:

🔒 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 - 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

Format Code

📁 What's Inside

🆘 Need Help?

Container won't start?

Just ask your AI assistant:

Can't connect to a host?

Let your AI assistant help troubleshoot:

Something else?

• Check logs: ~/.docker-mcp/data/logs/

• Debug mode: LOG_LEVEL=DEBUG

• Open an issue

🎉 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

Questions? Open an issue - we're here to help!