Docker MCP

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

Quick Start 🚀

For Cursor IDE Users

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

For Claude Desktop Users

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

Remote Docker Setup 🌐

For Remote VMs or Servers

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

SSH Config Integration

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

What Can Your AI Do? 🤖

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

Example Conversations

"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

Configuration Options ⚙️

Environment Variables

Common Configurations

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

Troubleshooting 🔧

Common Issues

"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

Getting Help

Run the diagnostic command:

npx docker-mcp --config

This will show your current configuration and help identify issues.

---

For Developers 🛠️

Available Tools

The MCP server provides these Docker management tools:

✅ Implemented 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

🚧 Planned Tools (Future Development)

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

Development Progress

Currently 8 out of 40 tools implemented (20%)

Manual Installation & Development

# 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

Testing the Server

# 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

Architecture

• 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

Contributing

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

License

MIT License - see LICENSE file for details.