# 🐳 Docker MCP Server

[![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://www.docker.com/)
[![Node.js](https://img.shields.io/badge/Node.js-43853D?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-FF6B6B?style=for-the-badge&logo=protocol&logoColor=white)](https://modelcontextprotocol.io/)
[![Claude](https://img.shields.io/badge/Claude-FA7B17?style=for-the-badge&logo=anthropic&logoColor=white)](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