A Model Context Protocol (MCP) server that enables AI assistants like Claude and Cursor IDE to interact with Docker containers. Your AI can now manage Docker containers, view logs, monitor resources, and troubleshoot issues without you needing to know Docker commands.

Stack: Node.js, TypeScript, dockerode, MCP

1. Install the package:

   npm install -g docker-mcp

2. Add to your Cursor settings:

   Open Cursor → Settings → Features → Model Context Protocol

   Add this configuration:

   {
     "mcpServers": {
       "docker": {
         "command": "npx",
         "args": ["-y", "docker-mcp"],
         "env": {
           "DOCKER_MCP_LOCAL": "true"
         }
       }
     }
   }

1. Install the package:

   npm install -g docker-mcp

2. Configure Claude Desktop:

   Edit your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json

   Add this configuration:

   {
     "mcpServers": {
       "docker": {
         "command": "npx",
         "args": ["-y", "docker-mcp"],
         "env": {
           "DOCKER_MCP_LOCAL": "true"
         }
       }
     }
   }

3. Restart Claude Desktop

If your Docker containers are running on a remote server or VM:

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "docker-mcp"],
      "env": {
        "DOCKER_MCP_HOST": "ssh://your-vm-name",
        "DOCKER_MCP_USERNAME": "ubuntu",
        "DOCKER_MCP_PRIVATE_KEY": "~/.ssh/id_rsa"
      }
    }
  }
}

If you have SSH hosts configured in ~/.ssh/config:

Host my-docker-vm
    HostName 192.168.1.100
    User ubuntu
    Port 22
    IdentityFile ~/.ssh/id_rsa

Then simply use:

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["-y", "docker-mcp"],
      "env": {
        "DOCKER_MCP_HOST": "ssh://my-docker-vm"
      }
    }
  }
}

Once configured, your AI assistant can help you with:

• 📦 Container Management: Start, stop, restart, and inspect containers
• 📋 Monitoring: View container logs, resource usage, and health status
• 🔍 Troubleshooting: Debug container issues, check port mappings, and analyze restarts
• 🧹 Cleanup: Remove unused images, volumes, and networks to free up space
• 🐳 Docker Compose: Manage multi-container applications
• 📊 System Info: Get Docker version, system information, and disk usage

"Show me all running containers" → AI will list all your containers with their status, ports, and resource usage

"Why did my nginx container restart 5 times?" → AI will check logs, detect restart loops, and help diagnose issues

"Clean up unused Docker resources" → AI will safely remove dangling images, unused volumes, and networks

"Show me the logs for my web server from the last hour" → AI will fetch and display recent logs with timestamps

Local Docker (most users):

{
  "env": {
    "DOCKER_MCP_LOCAL": "true"
  }
}

Remote Docker with VM name:

{
  "env": {
    "DOCKER_MCP_HOST": "ssh://my-docker-vm"
  }
}

Remote Docker with IP and credentials:

{
  "env": {
    "DOCKER_MCP_HOST": "ssh://192.168.1.100",
    "DOCKER_MCP_USERNAME": "ubuntu",
    "DOCKER_MCP_PRIVATE_KEY": "~/.ssh/id_rsa"
  }
}

"Cannot connect to Docker daemon"

• Make sure Docker is running on your system
• For remote hosts, verify SSH access: ssh your-vm-name

"Permission denied"

• Add your user to the docker group: sudo usermod -aG docker $USER
• For remote hosts, ensure the SSH user has Docker permissions

"Connection timeout"

• Check network connectivity to remote host
• Verify SSH key authentication is working

Run the diagnostic command:

npx docker-mcp --config

This will show your current configuration and help identify issues.

The MCP server provides these Docker management tools:

Container Management:

• docker_container_list - List all containers with status and details
• docker_container_inspect - Get detailed container information
• docker_container_start - Start a stopped container
• docker_container_stop - Stop a running container
• docker_container_restart - Restart a container
• docker_container_logs - Get container logs with time filtering

System Information:

• docker_system_info - Get Docker system information
• docker_system_version - Get Docker version details

Container Management (Extended):

• remove_container - Remove a container
• create_container - Create a new container from an image
• follow_container_logs - Stream live logs from a container
• get_container_stats - Get real-time resource usage statistics
• execute_in_container - Execute commands inside a running container
• detect_restart_loops - Detect containers that are restarting frequently
• container_processes - List processes running inside a container
• container_port_mappings - Show port mappings for containers
• container_file_changes - Show filesystem changes in a container
• export_container - Export container as tar archive
• copy_from_container - Copy files from container to host
• copy_to_container - Copy files from host to container

Docker Compose:

• compose_up - Start services defined in docker-compose.yml
• compose_down - Stop and remove compose services
• compose_pull - Pull latest images for compose services
• compose_logs - Get logs from compose services

Image Management:

• list_images - List available Docker images
• pull_image - Pull an image from a registry
• remove_image - Remove an image
• inspect_image - Get detailed image information

Network & Volume Management:

• list_networks - List Docker networks
• inspect_network - Get network details including connected containers
• list_volumes - List Docker volumes
• inspect_volume - Get volume details

System & Cleanup:

• system_df - Show Docker disk usage
• cleanup_unused_images - Remove unused/dangling images
• cleanup_unused_volumes - Remove unused volumes
• cleanup_unused_networks - Remove unused networks
• cleanup_unused_containers - Remove stopped containers
• cleanup_build_cache - Remove build cache
• cleanup_all - Comprehensive cleanup of all unused resources
• get_cleanup_summary - Show what would be cleaned up without removing

Currently 8 out of 40 tools implemented (20%)

# Clone and install dependencies
git clone https://github.com/sondt2709/docker-mcp.git
cd docker-mcp
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Show help
npx docker-mcp --help

# Show current configuration
npx docker-mcp --config

# Test with direct JSON-RPC (for development)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npx docker-mcp

• MCP Server: Built with @modelcontextprotocol/sdk
• Docker Integration: Uses dockerode for Docker API communication
• SSH Support: Native SSH connection via dockerode sshOptions
• Transport: Stdio transport for AI assistant communication

Contributions are welcome! Please feel free to submit a Pull Request.

MIT License - see LICENSE file for details.