Docker MCP Server

# Docker MCP Server Setup Guide 🐳 **Docker Model Context Protocol (MCP) Server** - Permite que IAs como Claude gerenciem containers Docker através do protocolo MCP. ## 📋 Prerequisites - **Node.js** >= 18.0.0 - **npm** >= 9.0.0 - **Docker Engine** funcionando - **Claude Code** ou **Claude Desktop** instalados - Usuário no grupo `docker` ou permissões root ### Verificar requisitos ```bash # Versões do Node/npm node --version # >= 18 npm --version # >= 9 # Docker funcionando docker info docker ps # Permissões Docker groups $USER | grep docker ``` ## 🚀 Installation ### 1. Clone ou navegue para o projeto ```bash cd /home/marcelo/docker/mcp-docker-server ``` ### 2. Instalar dependências ```bash npm install ``` ### 3. Configurar variáveis de ambiente ```bash # Copiar configuração padrão cp config/.env.example .env # Editar se necessário nano .env ``` ## ⚙️ Configuration ### Environment Variables | Variable | Description | Default | Example | |----------|-------------|---------|---------| | `DOCKER_SOCKET` | Path to Docker socket | `/var/run/docker.sock` | `/var/run/docker.sock` | | `DOCKER_HOST` | Docker daemon host | - | `192.168.1.10` | | `DOCKER_PORT` | Docker daemon port | `2375` | `2376` | | `DOCKER_PROTOCOL` | Connection protocol | `http` | `https` | | `DOCKER_SERVERS` | Multiple servers config | - | `local:socket:/var/run/docker.sock,remote:192.168.1.10:2375:http` | | `DOCKER_CERT_PATH` | TLS certificates path | - | `/path/to/certs` | | `LOG_LEVEL` | Logging level | `info` | `debug` | ### Single Docker Server (Local Socket) ```bash # .env DOCKER_SOCKET=/var/run/docker.sock LOG_LEVEL=info ``` ### Single Docker Server (Remote TCP) ```bash # .env DOCKER_HOST=192.168.1.10 DOCKER_PORT=2375 DOCKER_PROTOCOL=http LOG_LEVEL=info ``` ### Multiple Docker Servers ```bash # .env DOCKER_SERVERS=local:socket:/var/run/docker.sock,remote:192.168.1.10:2375:http,secure:prod.example.com:2376:https DOCKER_CERT_PATH_SECURE=/path/to/prod/certs LOG_LEVEL=info ``` ## 🎮 Usage ### Start Server ```bash # Using npm npm start # Using script ./scripts/start-server.sh # Background mode nohup npm start > logs/server.log 2>&1 & ``` ### Stop Server ```bash # Using script ./scripts/stop-server.sh # Manual pkill -f "mcp-docker-server" ``` ## 🔌 Claude Integration ### Option 1: Project-level (.claude/mcp.json) ```json { "servers": { "docker-local": { "type": "stdio", "command": "node", "args": ["src/index.js"], "env": { "DOCKER_SOCKET": "/var/run/docker.sock" }, "description": "Local Docker management via MCP" } } } ``` ### Option 2: Global Claude Desktop Add to Claude Desktop configuration: ```json { "mcpServers": { "docker-mcp": { "command": "node", "args": ["/home/marcelo/docker/mcp-docker-server/src/index.js"], "env": { "DOCKER_SOCKET": "/var/run/docker.sock" } } } } ``` ## 🛠️ Available Tools ### Container Management - `list_containers` - List all containers - `start_container` - Start a stopped container - `stop_container` - Stop a running container - `restart_container` - Restart a container - `remove_container` - Remove a container - `inspect_container` - Get detailed container info - `get_container_logs` - Retrieve container logs - `get_container_stats` - Get real-time statistics ### Image Management - `list_images` - List Docker images - `pull_image` - Pull image from registry - `remove_image` - Remove local image - `check_updates` - Check for image updates ### Network & Volume Management - `list_networks` - List Docker networks - `list_volumes` - List Docker volumes ### Docker Compose - `run_docker_compose` - Deploy from YAML content - `remove_docker_compose` - Remove compose project ### Server Management - `list_docker_servers` - List configured servers - `add_docker_server` - Add new server at runtime - `remove_docker_server` - Remove server configuration ## 📝 Example Requests ### List Containers ```bash # CLI test echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_containers","arguments":{"all":true}},"id":1}' | npm start ``` ### Start Container ```bash echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"start_container","arguments":{"containerId":"my-container"}},"id":2}' | npm start ``` ### Docker Compose Deploy ```yaml # Via Claude prompt "Deploy this Docker Compose configuration: version: '3.8' services: redis: image: redis:alpine ports: - '6379:6379'" ``` ## 🐛 Troubleshooting ### Common Issues #### Permission Denied (Docker Socket) ```bash # Add user to docker group sudo usermod -aG docker $USER # Reload groups newgrp docker # Verify access ls -la /var/run/docker.sock docker ps ``` #### Module Not Found Errors ```bash # Reinstall dependencies rm -rf node_modules package-lock.json npm install ``` #### Server Won't Start ```bash # Check logs cat logs/server-*.log # Manual debug DEBUG=* npm start # Check environment env | grep DOCKER ``` ### Debug Mode ```bash # Enable debug logging export LOG_LEVEL=debug npm start # Check Docker connectivity docker version docker system info ``` ### Firewall/Network Issues ```bash # Check Docker daemon is listening ss -tlnp | grep :2375 # Test TCP connection telnet docker-host 2375 ``` ## 📊 Monitoring ### Log Files ```bash # View real-time logs tail -f logs/server-*.log # Search for errors grep -i error logs/server-*.log ``` ### Health Checks ```bash # Basic connectivity test timeout 5s npm start < /dev/null # Container count check echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_containers","arguments":{}},"id":1}' | npm start | jq '.result.content[0].text | fromjson | length' ``` ## 🚨 Security Notes - **Docker socket access**: Grants root-equivalent privileges - **Remote Docker**: Use TLS certificates for production - **Network exposure**: Limit Docker API access by firewall - **Container permissions**: Review pulled images and configs - **Secrets**: Never commit credentials to version control ## 📚 Related Links - [Model Context Protocol](https://modelcontextprotocol.io/) - [Docker API Reference](https://docs.docker.com/engine/api/) - [Claude Code Documentation](https://docs.anthropic.com/claude-code) - [mcp-docker Package](https://www.npmjs.com/package/mcp-docker)