Docker MCP Server

Universal Docker MCP server for AI assistants (Cursor, Claude Desktop). Manage Docker containers, execute commands, query databases, and handle environment configurations — all through natural language.

✨ Features

• ✅ 20 MCP Commands — Container management, database operations, environment handling, resource monitoring, project discovery
• ✅ Database Support — PostgreSQL, Redis, SQLite with extensible adapter pattern
• ✅ Resource Monitoring — Container stats (CPU, Memory, Network, Block I/O), images, volumes, networks
• ✅ Auto-Discovery — Automatically finds and parses docker-compose.yml files (local and remote)
• ✅ Remote Docker — SSH support for managing remote Docker hosts
• ✅ Remote Project Discovery — Automatically find all Docker projects on remote servers
• ✅ Security — Automatic secrets masking in environment variables
• ✅ Follow Logs — Real-time log streaming with follow mode
• ✅ Type-Safe — Written in TypeScript with full type definitions
• ✅ Universal — Works with any Docker project

📦 Installation

Global Installation (Recommended)

npm install -g @hypnosis/docker-mcp-server

NPX (No Installation)

npx @hypnosis/docker-mcp-server

Local Installation

npm install @hypnosis/docker-mcp-server

🚀 Quick Start

Configuration for Cursor

Add to ~/.cursor/mcp.json (or ~/.config/cursor/mcp.json):

Local Docker (simplest - no configuration needed!):

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "@hypnosis/docker-mcp-server"]
    }
  }
}

That's it! The server will automatically detect and use your local Docker installation.

Optional: Enable auto-discovery and secret masking:

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "@hypnosis/docker-mcp-server"],
      "env": {
        "DOCKER_MCP_AUTO_DISCOVER": "true",
        "DOCKER_MCP_MASK_SECRETS": "true"
      }
    }
  }
}

Remote Docker (with profiles file):

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "@hypnosis/docker-mcp-server"],
      "env": {
        "DOCKER_MCP_PROFILES_FILE": "~/.docker-mcp/profiles.json"
      }
    }
  }
}

Create ~/.docker-mcp/profiles.json:

{
  "default": "production",
  "profiles": {
    "production": {
      "host": "prod.example.com",
      "username": "deployer",
      "port": 22,
      "privateKeyPath": "~/.ssh/id_rsa",
      "projectsPath": "/var/www"
    }
  }
}

Note: projectsPath specifies where to search for Docker projects on remote server (default: /var/www).

Note: If the profiles file doesn't exist or is invalid, the server will gracefully fall back to local Docker — no errors, no configuration needed!

Using Profiles in Commands

Starting from v1.3.0, you can specify a profile parameter in any command to work with remote servers:

// List containers on remote production server
docker_container_list({profile: "production"})

// Query database on remote server
docker_db_query({service: "postgres", query: "SELECT * FROM users;", profile: "production"})

// Check status on staging server
docker_container_stats({service: "web", profile: "staging"})

// Local Docker (default, no profile needed)
docker_container_list()  // Uses local Docker automatically

See Remote Docker Guide for detailed information about profiles and remote management.

Configuration for Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "@hypnosis/docker-mcp-server"]
    }
  }
}

First Steps

1. Restart your AI assistant (Cursor or Claude Desktop)
2. Navigate to your Docker project directory (with docker-compose.yml)
3. Ask your AI assistant:
   • "Show me the status of all containers"
   • "Restart the web service"
   • "Show me the last 50 lines of logs from the database"

📚 Available Commands

Container Management (9 commands)

Command	Description	Example
docker_container_list	List all containers (grouped by project)	docker_container_list()
docker_container_start	Start a container	docker_container_start({service: "web"})
docker_container_stop	Stop a container	docker_container_stop({service: "web"})
docker_container_restart	Restart a container	docker_container_restart({service: "web"})
docker_container_logs	View container logs	docker_container_logs({service: "web", follow: true, lines: 100})
docker_container_stats	Get container resource usage	docker_container_stats({service: "web"})
docker_compose_up	Start entire stack	docker_compose_up({build: true})
docker_compose_down	Stop entire stack	docker_compose_down({volumes: false})
docker_resource_list	List Docker images, volumes, or networks	docker_resource_list({type: "images"})

Database Operations (4 commands)

Command	Description	Example
docker_db_query	Execute SQL query or database command	docker_db_query({service: "postgres", query: "SELECT * FROM users LIMIT 5;"})
docker_db_backup	Create database backup	docker_db_backup({service: "postgres", compress: true})
docker_db_restore	Restore from backup	docker_db_restore({service: "postgres", backupPath: "./backup.sql"})
docker_db_status	Show database status	docker_db_status({service: "postgres"})

Environment & Config (3 commands)

Command	Description	Example
docker_env_list	List environment variables (with secret masking)	docker_env_list({service: "web", maskSecrets: true})
docker_compose_config	Show parsed compose config	docker_compose_config()
docker_healthcheck	Check health of all services	docker_healthcheck()

Universal Executor (1 command)

Command	Description	Example
docker_exec	Execute any command in container	docker_exec({service: "web", command: "npm test"})

Project Discovery (1 command)

Command	Description	Example
docker_projects	List all Docker projects with status (fast, ~2s)	docker_projects()

Note: For detailed container info, use docker_container_list({project: "project-name"}).

Utility Tools (2 commands)

Command	Description	Example
docker_mcp_health	Server diagnostics and health check	docker_mcp_health()
docker_profile_info	Show current profile and available profiles	docker_profile_info()

💡 Usage Examples

Example 1: Web Development (Next.js + Redis)

// Start the entire stack
docker_compose_up({build: true, detach: true})

// Check if services are healthy
docker_healthcheck()

// View logs in real-time
docker_container_logs({service: "web", follow: true, lines: 50})

// Check Redis cache
docker_db_query({service: "redis", query: "KEYS *"})

// Run tests
docker_exec({service: "web", command: "npm test"})

Example 2: Backend Development (Django + PostgreSQL)

// Restart backend after code changes
docker_container_restart({service: "web"})

// Run database migrations
docker_exec({service: "web", command: "python manage.py migrate"})

// Query database
docker_db_query({service: "postgres", query: "SELECT COUNT(*) FROM auth_user;"})

// Create backup before deployment
docker_db_backup({service: "postgres", compress: true})

// View application logs
docker_container_logs({service: "web", lines: 100, timestamps: true})

🏗️ How It Works

Project Discovery

The server automatically discovers your project structure:

1. Finds docker-compose.yml in current directory or parent directories
2. Parses project configuration (services, networks, volumes)
3. Detects database types (PostgreSQL, Redis, SQLite)
4. Loads environment files (.env, .env.local)
5. Masks secrets automatically (PASSWORD, TOKEN, KEY, etc.)

Database Adapters

Extensible adapter pattern for different databases:

• PostgreSQL — psql, pg_dump, pg_restore
• Redis — redis-cli, SAVE, BGSAVE
• SQLite — .dump, .restore
• More databases can be added via adapters

🔒 Security

Automatic Secrets Masking

Environment variables containing sensitive data are automatically masked:

// Original .env
DATABASE_PASSWORD=super_secret_123
API_TOKEN=abc123xyz

// Output from docker_env_list()
DATABASE_PASSWORD=***MASKED***
API_TOKEN=***MASKED***

Keywords that trigger masking: PASSWORD, TOKEN, KEY, SECRET, API_KEY

📖 Documentation

• Quick Start Guide — Detailed setup instructions
• API Reference — Complete command documentation
• Remote Docker Guide — SSH-based remote Docker management
• Remote Discovery Guide — Automatic project discovery on remote servers
• Examples — Real-world usage scenarios
• Testing System — Complete testing guide (E2E, Unit, Manual)
• Troubleshooting — Common issues and solutions
• FAQ — Frequently asked questions
• Roadmap — Future development plans and upcoming features

For developer documentation, see docs/DEV/README.md

Roadmap Overview

The project roadmap outlines planned features and releases. Key upcoming features include:

• v1.4.0 (Q1 2026): MySQL and MongoDB adapters
• v1.5.0 (Q2 2026): Enhanced monitoring and analytics
• v2.0.0 (Q3 2026): Plugin system and major architecture update
• v2.1.0 (Q4 2026): Network, volume, and image management

See docs/ROADMAP.md for detailed information about future plans, priorities, and how to contribute to the roadmap.

🤝 Contributing

We welcome contributions! This is an open-source project built for the community.

How to Contribute

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

See docs/DEV/README.md for development setup and guidelines.

📝 License

MIT License - see LICENSE for details

Copyright (c) 2025 Danila Susak

🙏 Acknowledgments

• Model Context Protocol by Anthropic
• Docker for containerization
• Community feedback and contributions

📬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for the AI-powered development community