Skip to content

jmagar/docker-mcp

BranchesTags

Repository files navigation

Docker Manager MCP

Docker Image Build Status Python 3.11+ FastMCP License: 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

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

🚀 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

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

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!

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors 5

Languages