Docker MCP

Una implementación en Ruby de un servidor MCP para gestionar y usar Docker

GitHub
2
Prueba este MCPPatrocinado

Documentación

DockerMCP

Un servidor de Model Context Protocol (MCP) que proporciona capacidades integrales de gestión de Docker a través de una interfaz estandarizada. Esta herramienta permite a los asistentes de IA y otros clientes MCP interactuar con contenedores, imágenes, redes y volúmenes de Docker de forma programática.

⚠️ Advertencia de Seguridad

Esta herramienta es inherentemente insegura y debe usarse con extrema precaución.

  • Ejecución de Código Arbitrario: La herramienta exec_container permite la ejecución de comandos arbitrarios dentro de contenedores Docker
  • Acceso al Sistema de Archivos: La herramienta copy_to_container puede copiar archivos del sistema host a los contenedores
  • Gestión de Contenedores: Gestión completa del ciclo de vida de contenedores, incluyendo creación, modificación y eliminación
  • Control de Redes y Volúmenes: Control total sobre redes y volúmenes de Docker

Recomendaciones:

  • Usar solo en entornos de confianza
  • Asegurar una configuración de seguridad adecuada del daemon de Docker
  • Considerar ejecutar con permisos restringidos de Docker
  • Monitorear y auditar todas las operaciones de contenedores
  • Tener precaución al exponer esta herramienta a clientes MCP externos o no confiables

Instalación

Instale la gema y agréguela al Gemfile de la aplicación ejecutando:

bundle add docker_mcp

Si no se está utilizando bundler para gestionar dependencias, instale la gema ejecutando:

gem install docker_mcp

Requisitos Previos

  • Docker Engine instalado y en ejecución
  • Ruby 3.2+
  • Permisos de Docker para el usuario que ejecuta el servidor MCP

Uso

Configuración del Cliente MCP

Agregue esto a su configuración de cliente MCP después de instalar la gema:

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

Ejemplo de Uso

Una vez configurado, puede usar las herramientas a través de su 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"

🔨 Herramientas

Este servidor MCP proporciona 22 herramientas integrales de gestión de Docker organizadas por funcionalidad:

Gestión de Contenedores

  • list_containers - Listar todos los contenedores Docker (en ejecución y detenidos) con información detallada
  • create_container - Crear un nuevo contenedor desde una imagen sin iniciarlo
  • run_container - Crear e iniciar inmediatamente un contenedor desde una imagen
  • start_container - Iniciar un contenedor detenido existente
  • stop_container - Detener un contenedor en ejecución de forma segura
  • remove_container - Eliminar un contenedor (debe estar detenido primero a menos que se fuerce)
  • recreate_container - Detener, eliminar y recrear un contenedor con la misma configuración
  • exec_container ⚠️ - Ejecutar comandos arbitrarios dentro de un contenedor en ejecución
  • fetch_container_logs - Recuperar registros de stdout/stderr de un contenedor
  • copy_to_container ⚠️ - Copiar archivos o directorios del host al contenedor

Gestión de Imágenes

  • list_images - Listar todas las imágenes Docker disponibles localmente
  • pull_image - Descargar una imagen de un registro Docker
  • push_image - Subir una imagen a un registro Docker
  • build_image - Construir una nueva imagen desde un Dockerfile
  • tag_image - Crear una nueva etiqueta para una imagen existente
  • remove_image - Eliminar una imagen del almacenamiento local

Gestión de Redes

  • list_networks - Listar todas las redes Docker
  • create_network - Crear una nueva red Docker
  • remove_network - Eliminar una red Docker

Gestión de Volúmenes

  • list_volumes - Listar todos los volúmenes Docker
  • create_volume - Crear un nuevo volumen Docker para datos persistentes
  • remove_volume - Eliminar un volumen Docker

Parámetros de Herramientas

La mayoría de las herramientas aceptan parámetros estándar de Docker:

  • ID/Nombre del Contenedor: Puede usar el ID completo del contenedor, ID corto o nombre del contenedor
  • Imagen: Especifique imágenes usando el formato name:tag (por ejemplo, nginx:latest, ubuntu:22.04)
  • Puertos: Use la sintaxis de mapeo de puertos de Docker (por ejemplo, "8080:80")
  • Volúmenes: Use la sintaxis de montaje de volúmenes de Docker (por ejemplo, "/host/path:/container/path")
  • Entorno: Establezca variables de entorno como pares KEY=VALUE

Casos de Uso Comunes

Configuración del Entorno de Desarrollo

# 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"

Depuración de Contenedores

# 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"

Gestión de Archivos

# 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/"

Manejo de Errores

El servidor proporciona mensajes de error detallados para problemas comunes:

  • Contenedor No Encontrado: Al hacer referencia a contenedores inexistentes
  • Imagen No Disponible: Al intentar usar imágenes que no están descargadas localmente
  • Permiso Denegado: Cuando el acceso al daemon de Docker está restringido
  • Conflictos de Red: Al crear redes con configuraciones conflictivas
  • Problemas de Montaje de Volúmenes: Cuando las rutas especificadas no existen o carecen de permisos

Todos los errores incluyen mensajes descriptivos para ayudar a diagnosticar y resolver problemas.

Solución de Problemas

Problemas de Conexión con el Daemon de Docker

# Check if Docker daemon is running
docker info

# Verify Docker permissions
docker ps

# Check MCP server logs for connection errors

Fallos en Operaciones de Contenedores

  • Asegúrese de que los IDs/nombres de contenedores sean correctos (use list_containers para verificar)
  • Verifique que los contenedores estén en el estado esperado (en ejecución/detenidos)
  • Verifique la disponibilidad de imágenes con list_images

Problemas de Permisos

  • Asegúrese de que el usuario que ejecuta el servidor MCP tenga permisos de Docker
  • Considere agregar al usuario al grupo docker: sudo usermod -aG docker $USER
  • Verifique los permisos del socket de Docker: ls -la /var/run/docker.sock

Limitaciones

  • Específico de Plataforma: Algunas operaciones de contenedores pueden comportarse de manera diferente entre sistemas operativos
  • Versión de la API de Docker: Requiere una versión compatible de la API del motor Docker
  • Límites de Recursos: Las copias de archivos grandes y las operaciones de imágenes pueden agotar el tiempo de espera
  • Operaciones Concurrentes: El uso concurrente intensivo puede afectar el rendimiento

Contribuciones

¡Damos la bienvenida a contribuciones! Áreas de mejora:

  • Seguridad Mejorada: Verificaciones de seguridad adicionales y validación de permisos
  • Mejor Manejo de Errores: Mensajes de error más específicos y sugerencias de recuperación
  • Optimización del Rendimiento: Transmisión para operaciones de archivos grandes
  • Funcionalidad Extendida: Soporte para Docker Compose, Swarm, etc.
  • Pruebas: Cobertura integral de pruebas para todas las herramientas

Desarrollo

Después de clonar el repositorio, ejecute bin/setup para instalar las dependencias. Luego, ejecute rake spec para ejecutar las pruebas. También puede ejecutar bin/console para un prompt interactivo que le permitirá experimentar.

Ejecución de Pruebas

# Install dependencies
bundle install

# Run the test suite
bundle exec rake spec

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

Configuración de Desarrollo 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

Pruebas con 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 gema en su máquina local, ejecute bundle exec rake install. Para publicar una nueva versión, actualice el número de versión en version.rb, y luego ejecute bundle exec rake release, que creará una etiqueta git para la versión, enviará los commits de git y la etiqueta creada, y enviará el archivo .gem a rubygems.org.

Licencia

La gema está disponible como código abierto bajo los términos de la Licencia MIT.