docker-vm-mcp

Creado por sundar.

Un servidor MCP que le da a un agente de IA control completo del ciclo de vida de las VM — crear, iniciar sesión por SSH, ejecutar comandos, detener/iniciar/reiniciar, eliminar, logs y estadísticas de recursos — sobre "VM" ligeras respaldadas por contenedores Docker. Cada VM es un sistema Ubuntu real que ejecuta un sshd real, con sudo y un disco persistente, por lo que se comporta como una máquina normal a la que puedes iniciar sesión — sin necesidad de cuenta en la nube ni virtualización anidada. El servidor en sí está contenedorizado y se publica como imagen Docker, y se controla completamente a través del Protocolo de Contexto de Modelo (MCP).

Una vez configurado, puedes simplemente pedirle a Claude cosas como:

• "Crea una VM llamada dev-box con 2 CPUs y 2GB de RAM"

• "Conéctame por SSH a dev-box" / "¿Cuál es el inicio de sesión SSH para dev-box?"

• "Instala nginx en dev-box y arráncalo"

• "Detén dev-box" / "Elimina dev-box"

• "Lista todas mis VM"

y Claude manejará todo el ciclo de vida a través de las herramientas que se muestran a continuación.

Cómo funciona

Cada "VM" es un contenedor Docker construido a partir de una imagen pequeña de Ubuntu 22.04 (vm-image/Dockerfile) que ejecuta un sshd real, tiene sudo y recibe un volumen Docker con nombre montado como su directorio de inicio (para que los archivos sobrevivan a detener/reiniciar, similar a un volumen EBS adjunto a una instancia EC2). El propio servidor MCP se comunica con tu daemon Docker local a través de /var/run/docker.sock — no ejecuta las VM en sí, sino que controla tu instalación existente de Docker Desktop.

Claude  <--MCP/stdio-->  docker-vm-mcp container  <--docker.sock-->  Docker Desktop
                                                                          |
                                                                    vm-dev-box (Ubuntu + sshd)
                                                                    vm-staging (Ubuntu + sshd)
                                                                    ...

Related MCP server: Docker MCP Server

Requisitos previos

• Docker Desktop instalado y en ejecución en tu Mac

• Node.js 20+ solo si quieres ejecutar el servidor fuera de Docker (no es necesario)

1. Compilar

Desde esta carpeta:

docker build -t docker-vm-mcp:latest .

Esto compila solo la imagen del servidor MCP. La imagen base de la VM (docker-vm-mcp/vm-base:latest) se compila automáticamente la primera vez que llamas a vm_create — el servidor incluye vm-image/Dockerfile y lo compila contra tu daemon Docker en el primer uso. También puedes precompilarla tú mismo:

docker build -t docker-vm-mcp/vm-base:latest ./vm-image

2. Ejecutar / registrar con Claude Desktop

Los servidores MCP sobre stdio son lanzados por el cliente (Claude Desktop), no se ejecutan de forma independiente. Añade esto a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "docker-vm-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "docker-vm-mcp-state:/data",
        "docker-vm-mcp:latest"
      ]
    }
  }
}

Luego reinicia Claude Desktop. Los dos montajes son obligatorios:

• /var/run/docker.sock — permite que el servidor cree/inicie/detenga/ejecute comandos en los contenedores de las VM en tu máquina.

• docker-vm-mcp-state (un volumen con nombre) — donde el servidor recuerda la contraseña SSH generada de cada VM entre reinicios. Sin él, vm_ssh_info pierde las contraseñas guardadas cada vez que el contenedor del servidor MCP se reinicia (los contenedores de las VM no se ven afectados — siguen ejecutándose).

Puedes verificar rápidamente que la imagen funciona y puede acceder a Docker antes de conectarla a Claude Desktop:

docker run -i --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v docker-vm-mcp-state:/data \
  docker-vm-mcp:latest
# should print nothing and just wait on stdin (that's correct — it's
# speaking MCP, not a REPL). Ctrl+C to exit.

Herramientas que expone este servidor

Iniciar sesión tú mismo

Cada VM vincula su puerto SSH a tu Mac, así que una vez que Claude crea una, también puedes conectarte por SSH directamente desde una terminal:

ssh vmuser@localhost -p <port>   # port and password from vm_create / vm_ssh_info

Pasa sshPublicKey a vm_create (el contenido de tu ~/.ssh/id_ed25519.pub) para omitir la contraseña e iniciar sesión con tu clave en su lugar.

Publicar esta imagen

Para compartirla (por ejemplo, para que un compañero u otra máquina pueda simplemente docker pull en lugar de compilar desde el código fuente):

docker tag docker-vm-mcp:latest <your-dockerhub-username>/docker-vm-mcp:latest
docker push <your-dockerhub-username>/docker-vm-mcp:latest

No hay nada secreto incrustado en la imagen — las credenciales se generan por VM en tiempo de ejecución y se almacenan solo en el volumen local docker-vm-mcp-state en la máquina que ejecuta el contenedor. Es seguro publicarla.

Notas de seguridad (léelas antes de exponer esto más allá de tu propia máquina)

• El montaje del socket Docker equivale a ser root. Cualquier cosa con acceso a /var/run/docker.sock puede controlar todos los contenedores de tu máquina, no solo las VM que crea esta herramienta. Ejecuta esta imagen con ese montaje solo en una máquina de confianza, y nunca expongas el servidor MCP en sí (ni un puerto hacia él) a llamadores no confiables.

• Las contraseñas SSH se almacenan en texto plano en el volumen docker-vm-mcp-state (/data/credentials.json) para que vm_ssh_info pueda devolvértelas más tarde. Eso está bien para una herramienta personal de desarrollo local; no la reutilices para uso multiinquilino o de producción sin endurecerla (por ejemplo, cambia a autenticación solo con clave y deja de persistir contraseñas).

• Los contenedores de las VM publican su puerto SSH en 0.0.0.0 por defecto (el valor predeterminado de Docker), lo que significa que otros dispositivos en tu red local podrían alcanzarlo si tu firewall lo permite. Pasa un sshPort explícito y protégelo con firewall, o vincúlalo solo a 127.0.0.1, si eso te importa (edita la IP del host de PortBindings en src/tools/createVm.ts a 127.0.0.1 y recompila).

Validación en el mundo real: ServiceNow Discovery

Este proyecto se ha utilizado como objetivo de Discovery en vivo para una instancia real de ServiceNow, a través de un MID Server ejecutado localmente (también contenedorizado) — prueba de que se comporta como un host Linux real accesible por SSH, no solo un juguete:

• Discovery estándar, MID Server → VM a través de la IP LAN del Mac y el puerto SSH publicado de la VM (por ejemplo, 192.168.x.x:<puerto>) — creó con éxito un CI cmdb_ci_linux_server con nombre de host, SO, RAM y detalles de CPU obtenidos en vivo a través de SSH.

• Quick Discovery también funciona de la misma manera.

• Dado que el contenedor del MID Server y el contenedor de la VM están ambos en la red bridge predeterminada de Docker, alternativamente pueden alcanzarse directamente por IP interna del contenedor en el puerto SSH estándar (22) — sin necesidad de puerto publicado, y sin dependencia de la IP LAN del Mac (que cambia entre redes).

• Una peculiaridad que vale la pena conocer si intentas esto tú mismo: el fabricante de la CPU descubierto aparece como "Apple". Eso es correcto, no es un error — Docker Desktop para Mac ejecuta contenedores dentro de una VM linuxkit arrancada directamente en el chip Apple Silicon del host, por lo que las sondas SSH que leen /proc/cpuinfo ven el hardware real subyacente, igual que lo harían en cualquier otro host.

Estructura del proyecto

docker-vm-mcp/
├── Dockerfile              # MCP server image
├── package.json
├── tsconfig.json
├── vm-image/
│   └── Dockerfile          # base "VM" image (Ubuntu + sshd), built on first vm_create
└── src/
    ├── index.ts            # MCP server entrypoint (stdio transport)
    ├── docker.ts            # Docker client, image-build, container lookup helpers
    ├── state.ts             # local credential store (/data/credentials.json)
    ├── util.ts              # exec/log demuxing helpers
    └── tools/
        ├── createVm.ts
        ├── listVms.ts
        ├── startVm.ts
        ├── stopVm.ts
        ├── restartVm.ts
        ├── deleteVm.ts
        ├── execVm.ts
        ├── sshInfo.ts
        ├── setPassword.ts
        ├── logsVm.ts
        └── statsVm.ts

Nota sobre cómo se verificó esto

Esto se construyó y verificó de tipos en un entorno aislado sin acceso al registro npm, por lo que npm install / npm run build no pudieron ejecutarse de extremo a extremo aquí. El TypeScript se verificó contra las definiciones de tipos propias de Node sin errores; las únicas comprobaciones restantes son contra los tipos de @modelcontextprotocol/sdk, dockerode y zod, que no se pudieron instalar en ese entorno aislado. Ejecuta esto una vez después de copiar el proyecto a tu Mac, antes de tu primer docker build:

npm install
npm run build

Si tsc informa algo más allá de lo que ya se ha manejado arriba, lo más probable es un cambio de API específico de versión en @modelcontextprotocol/sdk (es un paquete que se mueve rápido) — la solución casi siempre es un pequeño ajuste a las rutas de importación en src/index.ts (@modelcontextprotocol/sdk/server/mcp.js / .../server/stdio.js) para que coincidan con la versión que npm install haya resuelto.