FrenshGeek/claude-docker-mcp_controler

Claude Desktop Docker MCP Integration

A comprehensive, clean MCP (Model Context Protocol) server for controlling Docker Desktop through Claude Desktop. This implementation provides full Docker management capabilities with both custom server and Docker Gateway compatibility.

🎯 Features

Complete Docker Control

• Containers: Start, stop, restart, logs, stats, exec commands
• Images: List, pull, push, remove, build, inspect
• Networks: Create, list, remove, inspect
• Volumes: Create, list, remove, inspect
• System: Info, version, disk usage, cleanup/prune

Dual Integration Modes

1. Custom MCP Server: Full-featured Python implementation
2. Docker Gateway: Official Docker MCP integration
3. Both: Run both servers simultaneously for maximum compatibility

Production Ready

• Comprehensive error handling
• Security validation of Docker commands
• Structured JSON responses
• Full MCP protocol compliance
• Zero external dependencies (Python stdlib only)

🚀 Quick Setup

Prerequisites

• Docker Desktop installed and running
• Python 3.7+ (for custom server)
• Claude Desktop application

Automatic Setup

cd Claude_modifcation
python3 setup_claude_desktop.py

Choose option 3 (Both servers) for maximum compatibility.

Manual Setup

Option 1: Custom MCP Server

Copy claude_desktop_config.json content to your Claude Desktop config:

cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

Option 2: Docker Gateway Only

Copy claude_desktop_config_gateway.json instead:

cp claude_desktop_config_gateway.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

Restart Claude Desktop

Close and restart Claude Desktop completely for changes to take effect.

🧪 Testing

Test MCP Server

python3 test_mcp_server.py

Test Docker Integration

# Test Docker availability
docker --version

# Test Docker Gateway (if using)
docker mcp gateway --help

Test in Claude Desktop

Try these commands in Claude Desktop:

"List all my Docker containers"
"Show Docker system information"
"Pull the hello-world image"
"Show me my Docker images"
"Start container named jupyter_embedded_dd_vm"

📋 Available Tools

Container Management

• docker_ps - List containers (running or all)
• docker_start - Start containers
• docker_stop - Stop containers
• docker_restart - Restart containers
• docker_logs - Get container logs
• docker_stats - Show resource usage
• docker_exec - Execute commands in containers
• docker_inspect - Inspect containers

Image Management

• docker_images - List images
• docker_pull - Pull images from registry
• docker_push - Push images to registry
• docker_rmi - Remove images
• docker_build - Build images from Dockerfile

Network Management

• docker_network_ls - List networks
• docker_network_create - Create networks
• docker_network_rm - Remove networks

Volume Management

• docker_volume_ls - List volumes
• docker_volume_create - Create volumes
• docker_volume_rm - Remove volumes

System Management

• docker_info - System information
• docker_version - Version information
• docker_system_df - Disk usage
• docker_system_prune - Cleanup unused objects

Container Operations

• docker_run - Run new containers with full configuration

🔧 Configuration Details

Custom MCP Server Config

{
  "mcpServers": {
    "docker-desktop-mcp": {
      "command": "python3",
      "args": ["/path/to/docker_mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/Claude_modifcation"
      }
    }
  }
}

Docker Gateway Config

{
  "mcpServers": {
    "MCP_DOCKER_GATEWAY": {
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    }
  }
}

Combined Configuration

The setup script can configure both servers simultaneously, providing redundancy and maximum feature coverage.

🛡️ Security Features

• Command Validation: All Docker commands are validated and sanitized
• Argument Escaping: Shell injection protection via shlex.quote()
• Timeout Protection: Commands timeout after 30 seconds by default
• Error Isolation: Failures are contained and reported safely
• No Privileges: Server runs with user permissions only

🔍 Troubleshooting

MCP Server Not Starting

1. Check Python path in configuration
2. Verify script permissions: chmod +x docker_mcp_server.py
3. Test manually: python3 docker_mcp_server.py

Docker Commands Failing

1. Verify Docker Desktop is running
2. Test Docker CLI: docker ps
3. Check Docker permissions

Claude Desktop Not Recognizing Server

1. Verify configuration file location
2. Restart Claude Desktop completely
3. Check Claude Desktop logs for MCP errors

Docker Gateway Issues

1. Update Docker Desktop to latest version
2. Test gateway: docker mcp gateway --help
3. Try custom server as fallback

📁 File Structure

Claude_modifcation/
├── docker_mcp_server.py              # Main MCP server implementation
├── claude_desktop_config.json        # Custom server configuration
├── claude_desktop_config_gateway.json # Docker Gateway configuration
├── setup_claude_desktop.py           # Automatic setup script
├── test_mcp_server.py                # Test suite
├── requirements.txt                  # Dependencies (none required)
└── README.md                         # This documentation

🎨 Example Usage

Basic Container Management

Claude: "Show me all my Docker containers"
> Lists all containers with status

Claude: "Start the container named web-server"
> Starts the specified container

Claude: "Get the logs for my nginx container"
> Retrieves and displays container logs

System Management

Claude: "Show Docker system information and disk usage"
> Displays comprehensive system info

Claude: "Clean up unused Docker objects to free space"
> Performs system cleanup

Development Workflow

Claude: "Pull the latest Ubuntu image"
> Downloads Ubuntu image

Claude: "Run a temporary Ubuntu container with bash"
> Creates and starts interactive container

Claude: "Build a Docker image from the current directory"
> Builds image using local Dockerfile

🔄 Integration with Docker Gateway

This implementation is designed to be compatible with Docker's official MCP Gateway:

• Follows MCP protocol specifications
• Uses standard Docker CLI commands
• Provides structured JSON responses
• Maintains compatibility with Docker Gateway tools

You can run both the custom server and Docker Gateway simultaneously for maximum coverage and redundancy.

🤝 Contributing

The server is designed to be easily extensible:

1. Add new tools to get_available_tools()
2. Implement tool handlers in handle_tool_call()
3. Follow the existing pattern for error handling
4. Test with the provided test suite

📝 License

This implementation uses only Python standard library and Docker CLI, ensuring compatibility and minimal dependencies.