Docker MCP

Uma implementação em Ruby de um servidor MCP para gerenciar e usar Docker

GitHub
2
Experimente este MCPPatrocinado

Documentação

DockerMCP

Um servidor Model Context Protocol (MCP) que fornece recursos abrangentes de gerenciamento do Docker por meio de uma interface padronizada. Esta ferramenta permite que assistentes de IA e outros clientes MCP interajam programaticamente com contêineres, imagens, redes e volumes do Docker.

⚠️ Aviso de Segurança

Esta ferramenta é inerentemente insegura e deve ser usada com extrema cautela.

  • Execução de Código Arbitrário: A ferramenta exec_container permite a execução de comandos arbitrários dentro de contêineres Docker
  • Acesso ao Sistema de Arquivos: A ferramenta copy_to_container pode copiar arquivos do sistema host para contêineres
  • Gerenciamento de Contêineres: Gerenciamento completo do ciclo de vida dos contêineres, incluindo criação, modificação e exclusão
  • Controle de Redes e Volumes: Controle total sobre redes e volumes do Docker

Recomendações:

  • Use apenas em ambientes confiáveis
  • Garanta uma configuração de segurança adequada do daemon do Docker
  • Considere executar com permissões restritas do Docker
  • Monitore e audite todas as operações de contêineres
  • Tenha cuidado ao expor esta ferramenta a clientes MCP externos ou não confiáveis

Instalação

Instale a gem e adicione ao Gemfile da aplicação executando:

bundle add docker_mcp

Se o bundler não estiver sendo usado para gerenciar dependências, instale a gem executando:

gem install docker_mcp

Pré-requisitos

  • Docker Engine instalado e em execução
  • Ruby 3.2+
  • Permissões do Docker para o usuário que executa o servidor MCP

Uso

Configuração do Cliente MCP

Adicione isto à configuração do seu cliente MCP após instalar a gem:

{
  "docker_mcp": {
    "command": "bash",
    "args": [
      "-l",
      "-c",
      "docker_mcp"
    ]
  }
}

Exemplo de Uso

Após a configuração, você pode usar as ferramentas por meio do seu cliente MCP:

# List all containers
list_containers

# Create and run a new container
run_container image="nginx:latest" name="my-web-server"

# Execute commands in a container
exec_container id="my-web-server" cmd="nginx -v"

# Copy files to a container
copy_to_container id="my-web-server" source_path="/local/file.txt" destination_path="/var/www/html/"

# View container logs
fetch_container_logs id="my-web-server"

🔨 Ferramentas

Este servidor MCP fornece 22 ferramentas abrangentes de gerenciamento do Docker organizadas por funcionalidade:

Gerenciamento de Contêineres

  • list_containers - Lista todos os contêineres Docker (em execução e parados) com informações detalhadas
  • create_container - Cria um novo contêiner a partir de uma imagem sem iniciá-lo
  • run_container - Cria e inicia imediatamente um contêiner a partir de uma imagem
  • start_container - Inicia um contêiner parado existente
  • stop_container - Para um contêiner em execução de forma graciosa
  • remove_container - Exclui um contêiner (deve ser parado primeiro, a menos que forçado)
  • recreate_container - Para, remove e recria um contêiner com a mesma configuração
  • exec_container ⚠️ - Executa comandos arbitrários dentro de um contêiner em execução
  • fetch_container_logs - Recupera logs de stdout/stderr de um contêiner
  • copy_to_container ⚠️ - Copia arquivos ou diretórios do host para o contêiner

Gerenciamento de Imagens

  • list_images - Lista todas as imagens Docker disponíveis localmente
  • pull_image - Baixa uma imagem de um registro Docker
  • push_image - Envia uma imagem para um registro Docker
  • build_image - Constrói uma nova imagem a partir de um Dockerfile
  • tag_image - Cria uma nova tag para uma imagem existente
  • remove_image - Exclui uma imagem do armazenamento local

Gerenciamento de Redes

  • list_networks - Lista todas as redes Docker
  • create_network - Cria uma nova rede Docker
  • remove_network - Exclui uma rede Docker

Gerenciamento de Volumes

  • list_volumes - Lista todos os volumes Docker
  • create_volume - Cria um novo volume Docker para dados persistentes
  • remove_volume - Exclui um volume Docker

Parâmetros das Ferramentas

A maioria das ferramentas aceita parâmetros padrão do Docker:

  • ID/Nome do Contêiner: Pode usar o ID completo do contêiner, ID curto ou nome do contêiner
  • Imagem: Especifique imagens usando o formato name:tag (ex.: nginx:latest, ubuntu:22.04)
  • Portas: Use a sintaxe de mapeamento de portas do Docker (ex.: "8080:80")
  • Volumes: Use a sintaxe de montagem de volumes do Docker (ex.: "/host/path:/container/path")
  • Ambiente: Defina variáveis de ambiente como pares KEY=VALUE

Casos de Uso Comuns

Configuração de Ambiente de Desenvolvimento

# Pull development image
pull_image from_image="node:18-alpine"

# Create development container with volume mounts
run_container image="node:18-alpine" name="dev-env" \
  host_config='{"PortBindings":{"3000/tcp":[{"HostPort":"3000"}]},"Binds":["/local/project:/app"]}'

# Execute development commands
exec_container id="dev-env" cmd="npm install"
exec_container id="dev-env" cmd="npm start"

Depuração de Contêineres

# Check container status
list_containers

# View container logs
fetch_container_logs id="problematic-container"

# Execute diagnostic commands
exec_container id="problematic-container" cmd="ps aux"
exec_container id="problematic-container" cmd="df -h"
exec_container id="problematic-container" cmd="netstat -tlnp"

Gerenciamento de Arquivos

# Copy configuration files to container
copy_to_container id="web-server" \
  source_path="/local/nginx.conf" \
  destination_path="/etc/nginx/"

# Copy application code
copy_to_container id="app-container" \
  source_path="/local/src" \
  destination_path="/app/"

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para problemas comuns:

  • Contêiner Não Encontrado: Ao referenciar contêineres inexistentes
  • Imagem Indisponível: Ao tentar usar imagens que não foram baixadas localmente
  • Permissão Negada: Quando o acesso ao daemon do Docker está restrito
  • Conflitos de Rede: Ao criar redes com configurações conflitantes
  • Problemas de Montagem de Volume: Quando os caminhos especificados não existem ou não têm permissões

Todos os erros incluem mensagens descritivas para ajudar a diagnosticar e resolver problemas.

Solução de Problemas

Problemas de Conexão com o Daemon do Docker

# Check if Docker daemon is running
docker info

# Verify Docker permissions
docker ps

# Check MCP server logs for connection errors

Falhas em Operações de Contêineres

  • Garanta que os IDs/nomes dos contêineres estejam corretos (use list_containers para verificar)
  • Verifique se os contêineres estão no estado esperado (em execução/parados)
  • Verifique a disponibilidade da imagem com list_images

Problemas de Permissão

  • Garanta que o usuário que executa o servidor MCP tenha permissões do Docker
  • Considere adicionar o usuário ao grupo docker: sudo usermod -aG docker $USER
  • Verifique as permissões do socket do Docker: ls -la /var/run/docker.sock

Limitações

  • Específico da Plataforma: Algumas operações de contêineres podem se comportar de forma diferente entre sistemas operacionais
  • Versão da API do Docker: Requer uma versão compatível da API do Docker Engine
  • Limites de Recursos: Cópias de arquivos grandes e operações de imagem podem expirar
  • Operações Concorrentes: Uso concorrente intenso pode impactar o desempenho

Contribuindo

Aceitamos contribuições! Áreas para melhoria:

  • Segurança Aprimorada: Verificações de segurança adicionais e validação de permissões
  • Melhor Tratamento de Erros: Mensagens de erro mais específicas e sugestões de recuperação
  • Otimização de Desempenho: Streaming para operações de arquivos grandes
  • Funcionalidade Estendida: Suporte para Docker Compose, Swarm, etc.
  • Testes: Cobertura abrangente de testes para todas as ferramentas

Desenvolvimento

Após clonar o repositório, execute bin/setup para instalar as dependências. Em seguida, execute rake spec para rodar os testes. Você também pode executar bin/console para um prompt interativo que permitirá experimentar.

Executando Testes

# Install dependencies
bundle install

# Run the test suite
bundle exec rake spec

# Run tests with coverage
bundle exec rake spec COVERAGE=true

Configuração de Desenvolvimento Local

# Clone the repository
git clone https://github.com/afstanton/docker_mcp.git
cd docker_mcp

# Install dependencies
bin/setup

# Start development console
bin/console

# Build the gem locally
bundle exec rake build

# Install locally built gem
bundle exec rake install

Testando com Cliente MCP

# Start the MCP server locally
bundle exec exe/docker_mcp

# Configure your MCP client to use local development server
# Use file path instead of installed gem command

Para instalar esta gem em sua máquina local, execute bundle exec rake install. Para lançar uma nova versão, atualize o número da versão em version.rb e, em seguida, execute bundle exec rake release, que criará uma tag git para a versão, enviará os commits do git e a tag criada, e enviará o arquivo .gem para rubygems.org.

Licença

A gem está disponível como código aberto sob os termos da Licença MIT.