🐳 Docker MCP Server

Docker Model Context Protocol (MCP) Server - Permite que IAs como Claude gerenciem containers Docker através do protocolo MCP de forma segura e intuitiva.

🌟 Features

• 🔧 Gerenciamento completo de containers: Start, stop, restart, logs, estatísticas
• 📦 Controle de imagens: Pull, remove, verificar atualizações
• 🐳 Docker Compose: Deploy e remoção de stacks via YAML
• 🌐 Múltiplos servidores: Conectar a vários Docker hosts simultâneamente
• 🔒 Segurança: Socket Unix local ou TCP com TLS
• 📊 Monitoramento: Logs estruturados e métricas em tempo real
• ⚡ Integração Claude: Pronto para uso com Claude Code/Desktop

🚀 Quick Start

# 1. Navegar para o diretório
cd /home/marcelo/docker/mcp-docker-server

# 2. Instalar dependências
npm install

# 3. Configurar ambiente (opcional)
cp config/.env.example .env

# 4. Iniciar servidor
npm start

📋 Prerequisites

• Node.js >= 18.0.0
• Docker Engine funcionando
• Usuário no grupo docker
• Claude Code ou Claude Desktop

🛠️ Available Tools

Category	Tools	Description
Containers	list_containers, start_container, stop_container, restart_container	Gerenciamento completo de containers
Images	list_images, pull_image, remove_image, check_updates	Controle de imagens Docker
Compose	run_docker_compose, remove_docker_compose	Deploy via YAML inline
Networks/Volumes	list_networks, list_volumes	Visualização de recursos
Servers	list_docker_servers, add_docker_server	Multi-host management

🔌 Claude Integration

Método 1: Configuração de projeto

Criar .claude/mcp.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"
    }
  }
}

Método 2: Claude Desktop global

Ver exemplos em config/claude-desktop-sample.json.

📖 Examples

Listar containers via Claude

"Liste todos os containers Docker ativos e parados"

Deploy Docker Compose via Claude

"Deploy este Docker Compose:

version: '3.8'
services:
  redis:
    image: redis:alpine
    ports:
      - '6379:6379'"

Gerenciar container específico

"Reinicie o container 'nginx-proxy' e mostre os logs recentes"

📁 Project Structure

mcp-docker-server/
├── src/
│   └── index.js              # Servidor principal
├── scripts/
│   ├── start-server.sh       # Script de inicialização
│   └── stop-server.sh        # Script de parada
├── config/
│   ├── .env.example          # Configuração de ambiente
│   ├── claude-desktop-sample.json
│   └── env.sample.sh
├── docs/
│   └── SETUP.md             # Documentação completa
├── logs/                    # Logs de execução
├── .claude/
│   └── mcp.json            # Configuração MCP do projeto
└── package.json

⚙️ Configuration

Socket Unix (Padrão)

DOCKER_SOCKET=/var/run/docker.sock

Docker remoto

DOCKER_HOST=192.168.1.10
DOCKER_PORT=2375
DOCKER_PROTOCOL=http

Múltiplos servidores

DOCKER_SERVERS=local:socket:/var/run/docker.sock,prod:prod-docker:2376:https

🐛 Troubleshooting

Erro de permissão

sudo usermod -aG docker $USER
newgrp docker

Dependências

rm -rf node_modules package-lock.json
npm install

Debug

export LOG_LEVEL=debug
npm start

📊 Monitoring

# Logs em tempo real
tail -f logs/server-*.log

# Status básico
timeout 5s npm start < /dev/null

🚨 Security Notes

⚠️ IMPORTANTE: O acesso ao socket Docker concede privilégios equivalentes ao root. Use apenas em ambientes confiáveis.

• Socket local: Preferir quando possível
• TCP remoto: Sempre usar TLS em produção
• Firewall: Limitar acesso às portas Docker
• Containers: Revisar imagens antes de executar

📚 Documentation

• 📖 Setup Guide - Guia completo de instalação e configuração
• 🔧 Troubleshooting - Solução de problemas comuns
• 🔌 Claude Integration - Integração com Claude
• 🛠️ Available Tools - Lista completa de ferramentas

📝 License

MIT License - Ver arquivo LICENSE para detalhes.

🤝 Contributing

1. Fork o projeto
2. Criar feature branch (git checkout -b feature/nova-funcionalidade)
3. Commit as mudanças (git commit -am 'Adiciona nova funcionalidade')
4. Push to branch (git push origin feature/nova-funcionalidade)
5. Abrir Pull Request

⭐ Support

Gostou do projeto? Deixe uma estrela ⭐

Encontrou algum problema? Abra uma issue 🐛

---

Criado por: Marcelo Matos
Baseado em: mcp-docker por FlorentB974