mcp-docker-server by marcelofmatos - MCP Server

🐳 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

📖 - Guia completo de instalação e configuração
🔧 - Solução de problemas comuns
🔌 - Integração com Claude
🛠️ - Lista completa de ferramentas

📝 License

MIT License - Ver arquivo para detalhes.

🤝 Contributing

Fork o projeto
Criar feature branch (git checkout -b feature/nova-funcionalidade)
Commit as mudanças (git commit -am 'Adiciona nova funcionalidade')
Push to branch (git push origin feature/nova-funcionalidade)
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