Docker MCP

🚀 Docker Manager MCP

Control all your Docker hosts from one place. Docker Manager MCP enables AI assistants to manage containers, deploy stacks, and monitor services across your entire infrastructure with zero configuration needed.

🚀 Quick Start

One-Line Install

curl -sSL https://raw.githubusercontent.com/jmagar/docker-mcp/main/install.sh | bash

That's it! The installer:

• ✅ Automatically sets up SSH keys
• ✅ 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.

✨ Features

🎯 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"

🔧 Technical Details

🏗 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

💻 Usage Examples

Deploy a WordPress Site

# 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

📚 Documentation

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

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

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:

# 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

git clone https://github.com/jmagar/docker-mcp
cd docker-mcp
uv sync
uv run docker-mcp

Format Code

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

🎉 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

# 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 - we're here to help!