Docker MCP Server

Este projeto oferece um Minimal Control Plane (MCP) para gerenciar contêineres e volumes Docker localmente com Dockerode, sem chamar shell.

Pré‑requisitos

• Node.js ≥ 18
• npm ou yarn
• Docker rodando localmente (socket padrão ou DOCKER_HOST configurado)

Instalação

git clone <repo>
cd docker-mcp-server
npm install

Como usar

# Desenvolvimento (auto‑reload)
npm run dev 

# Produção:
npm run build
npm start

O servidor escuta na porta 3000 (ou a porta que você definir via PORT).

API

Método	Endpoint	Descrição
GET	/api/containers	Lista contêineres (?all=true, ?status=running, etc.)
GET	/api/containers/:id	Inspeção
GET	/api/containers/:id/logs	Logs (since, tail, follow)
POST	/api/containers/:id/start	Inicia
POST	/api/containers/:id/stop	Para
POST	/api/containers/:id/restart	Reinicia
GET	/api/containers/:id/stats	Estatísticas snapshot
POST	/api/containers/:id/exec	Execute comando ({cmd: ["ls", "/"]})
DELETE	/api/containers/:id	Remove contêiner (force)
DELETE	/api/volumes/:name	Remove volume

Estrutura

src/
├─ index.ts
├─ server.ts
├─ routes/docker.routes.ts
├─ controllers/docker.controller.ts
├─ services/docker.service.ts
├─ dto/docker.dto.ts
└─ utils/errorHandler.ts

Contribuição

Sinta‑se à vontade para abrir issues/pulls. Mantenha a mesma estrutura de validação + controller + service.

Licença

MIT

Uso na pratica

Para usar o MCP foi iniciado a aplicação, e dado o contexto no claude code com um prompt simples:

Você tem acesso a uma API local para gerenciamento de Docker em:
                                                                  
  http://127.0.0.1:3000/api                                       
                                                                  
  Use essa API sempre que eu pedir algo relacionado a containers ou volumes Docker.
  Não assuma o estado dos containers sem consultar a API.         
                                                                  
  Endpoints disponíveis:                                          
  - `GET /containers?all=true` → lista todos os containers        
  - `GET /containers?status=running` → lista apenas os containers em execução
  - `GET /containers/:id` → inspeciona um container               
  - `GET /containers/:id/logs?tail=100` → mostra logs             
  - `POST /containers/:id/start` → inicia um container            
  - `POST /containers/:id/stop` → para um container               
  - `POST /containers/:id/restart` → reinicia um container        
  - `GET /containers/:id/stats` → mostra estatísticas             
  - `POST /containers/:id/exec` → executa comando no container    
  - `DELETE /containers/:id` → remove um container                
  - `DELETE /volumes/:name` → remove um volume                    
                                                                  
  Regras:                                                         
  - Sempre use a API antes de responder sobre Docker.             
  - Para ações destrutivas como `stop`, `restart`, `remove` e `DELETE`, confirme comigo antes de executar.
  - Se eu pedir um resumo dos containers, liste usando a API.     
  - Se eu pedir logs, use o endpoint de logs.                     
  - Se eu pedir execução de comando, use o endpoint `exec`.       
  - Se a API estiver fora do ar, informe isso claramente.         
                                                                  
  Exemplos de uso:                                                
  - listar containers: `curl 'http://127.0.0.1:3000/api/containers?all=true'`
  - listar running: `curl 'http://127.0.0.1:3000/api/containers?status=running'`
  - inspecionar: `curl 'http://127.0.0.1:3000/api/containers/zabbix-server'`
  - logs: `curl 'http://127.0.0.1:3000/api/containers/zabbix-server/logs?tail=100'`
  - restart: `curl -X POST 'http://127.0.0.1:3000/api/containers/zabbix-server/restart'`
  - exec: `curl -X POST 'http://127.0.0.1:3000/api/containers/zabbix-server/exec' -H 'Content-Type: application/json' -d
  '{"cmd":["ls","/"]}'`                                           
  - remove volume: `curl -X DELETE 'http://127.0.0.1:3000/api/volumes/meu-volume'`