README.md•5.78 kB
# 🐳 Docker MCP Server
[](https://www.docker.com/)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](https://claude.ai/)
**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
```bash
# 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`:
```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)
```bash
DOCKER_SOCKET=/var/run/docker.sock
```
### Docker remoto
```bash
DOCKER_HOST=192.168.1.10
DOCKER_PORT=2375
DOCKER_PROTOCOL=http
```
### Múltiplos servidores
```bash
DOCKER_SERVERS=local:socket:/var/run/docker.sock,prod:prod-docker:2376:https
```
## 🐛 Troubleshooting
### Erro de permissão
```bash
sudo usermod -aG docker $USER
newgrp docker
```
### Dependências
```bash
rm -rf node_modules package-lock.json
npm install
```
### Debug
```bash
export LOG_LEVEL=debug
npm start
```
## 📊 Monitoring
```bash
# 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](docs/SETUP.md)** - Guia completo de instalação e configuração
- 🔧 **[Troubleshooting](docs/SETUP.md#troubleshooting)** - Solução de problemas comuns
- 🔌 **[Claude Integration](docs/SETUP.md#claude-integration)** - Integração com Claude
- 🛠️ **[Available Tools](docs/SETUP.md#available-tools)** - Lista completa de ferramentas
## 📝 License
MIT License - Ver arquivo [LICENSE](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](https://github.com/marcelofmatos)
**Baseado em**: [mcp-docker](https://www.npmjs.com/package/mcp-docker) por FlorentB974