# Generar archivos de Docker Compose con Claude Code y Docker MCP Toolkit


Esta guía te introduce al uso de Claude Code junto con Docker MCP Toolkit para que Claude pueda buscar en Docker Hub en tiempo real y generar un `docker-compose.yaml` completo a partir de lenguaje natural.

En lugar de escribir YAML manualmente o buscar etiquetas de imágenes, describes tu stack una vez; Claude utiliza el Model Context Protocol (MCP) para consultar Docker Hub y crear un archivo de Compose listo para producción.

En esta guía, aprenderás a:

- Habilitar Docker MCP Toolkit en Docker Desktop
- Agregar el servidor MCP de Docker Hub
- Conectar Claude Code al MCP Gateway (GUI o CLI)
- Verificar la conectividad de MCP dentro de Claude
- Pedir a Claude que genere y guie un archivo de Compose para una aplicación de Node.js + PostgreSQL
- Desplegarlo al instante con `docker compose up`

---

## Usar Claude Code y Docker MCP Toolkit para generar un archivo de Docker Compose a partir de lenguaje natural

- **Configuración**: Habilitar MCP Toolkit → Agregar el servidor MCP de Docker Hub → Conectar Claude Code
- **Uso de Claude**: Describe tu stack en lenguaje natural
- **Automatización**: Claude consulta Docker Hub a través de MCP y crea un `docker-compose.yaml` completo
- **Despliegue**: Ejecutar `docker compose up` → Node.js + PostgreSQL en vivo en `localhost:3000`
- **Beneficio**: Cero escritura de YAML. Cero búsqueda de imágenes. Describe una vez → Claude lo construye.

**Tiempo estimado**: ~15 minutos

---

## 1. Qué vas a construir

El objetivo es directo: usar Claude Code junto con Docker MCP Toolkit para buscar imágenes en Docker Hub y generar un archivo de Docker Compose completo para una configuración de Node.js y PostgreSQL.

El Model Context Protocol (MCP) conecta Claude Code y Docker Desktop, proporcionando a Claude acceso en tiempo real a las herramientas de Docker. En lugar de cambiar de contexto entre Docker, comandos de terminal y editores de YAML, describes tus requisitos una vez y Claude se encarga de los detalles de la infraestructura.

**Por qué es importante:** Este patrón se escala a configuraciones complejas de múltiples servicios, migraciones de bases de datos, redes, políticas de seguridad; todo a través de prompts conversacionales.

---

## 2. Requisitos previos

Asegúrate de tener:

- Docker Desktop instalado
- Docker Desktop actualizado con soporte para [MCP Toolkit](https://docs-docker.esdocu.com/ai/mcp-catalog-and-toolkit/get-started/#setup)
- Claude Code instalado

---

## 3. Instalar el servidor MCP de Docker Hub

1. Abre **Docker Desktop**
1. Selecciona **MCP Toolkit**
1. Ve a la pestaña **Catalog**
1. Busca **Docker Hub**
1. Selecciona el servidor MCP de **Docker Hub**
1. Agrega el servidor MCP, luego abre la pestaña **Configuration**
1. Introduce tu nombre de usuario de Docker Hub
1. [Crea un token de acceso personal de solo lectura](/security/access-tokens/#create-a-personal-access-token) e introduce tu token de acceso en **Secrets**
1. Guarda la configuración

![Docker Hub](/guides/genai-claude-code-mcp/Images/catalog_docker_hub.avif "Docker Hub")

Las imágenes públicas funcionan sin credenciales. Para repositorios privados, puedes agregar tu nombre de usuario y token de Docker Hub más tarde.

![Docker Hub Secrets](/guides/genai-claude-code-mcp/Images/dockerhub_secrets.avif "Docker Hub Secrets")

---

## 4. Conectar Claude Code a Docker MCP Toolkit

Puedes realizar la conexión desde Docker Desktop o usando la CLI.

### Opción A. Conectar con Docker Desktop

1. Abre **MCP Toolkit**
1. Ve a la pestaña **Clients**
1. Localiza **Claude Code**
1. Selecciona **Connect**

![Docker Connection](/guides/genai-claude-code-mcp/Images/docker-connect-claude.avif)

### Opción B. Conectar usando la CLI

```console
$ claude mcp add MCP_DOCKER -s user -- docker mcp gateway run
```

---

## 5. Verificar los servidores MCP dentro de Claude Code

1. Navega a la carpeta de tu proyecto:

```console
$ cd /path/to/project
```

1. Inicia Claude Code:

```console
$ claude
```

1. En el cuadro de entrada, escribe:

```console
/mcp
```

Deberías ver lo siguiente:

- El gateway de MCP (por ejemplo `MCP_DOCKER`)
- Las herramientas proporcionadas por el servidor MCP de Docker Hub

![mcp-docker](/guides/genai-claude-code-mcp/Images/mcp-servers.avif)

Si no es así, reinicia Claude Code o consulta Docker Desktop para confirmar la conexión.

---

## 6. Crear una aplicación básica de Node.js

Claude Code genera archivos de Compose más precisos cuando puede inspeccionar un proyecto real. Configura el código de la aplicación ahora para que el agente pueda realizar el montaje de tipo bind más tarde.

Dentro de la carpeta del proyecto, crea una carpeta llamada `app`:

```console
$ mkdir app
$ cd app
$ npm init -y
$ npm install express
```

Crea `index.js`:

```javascript
const express = require("express");
const app = express();

app.get("/", (req, res) => {
  res.send("Node.js, Docker, and MCP Toolkit are working together!");
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});
```

Agrega un script de inicio a `package.json`:

```json
"scripts": {
  "start": "node index.js"
}
```

Regresa a la raíz de tu proyecto (`cd ..`) una vez que la aplicación esté lista.

---

## 7. Pedir a Claude Code que diseñe tu stack de Docker Compose

Pega este mensaje en Claude Code:

```console
Usando el servidor MCP de Docker Hub:

Busca en Docker Hub una imagen oficial de Node.js y una imagen de PostgreSQL.
Elige etiquetas estables y de uso común, como la versión LTS de Node y una versión principal reciente de Postgres.

Genera un archivo de Docker Compose (`docker-compose.yaml`) con:
- app:
  - se ejecuta en el puerto 3000
  - realiza un montaje de tipo bind del directorio ./app existente en /usr/src/app
  - establece /usr/src/app como directorio de trabajo y ejecuta `npm install && npm start`
- db: se ejecuta en el puerto 5432 usando un volumen con nombre

Incluye:
- Variables de entorno para Postgres
- Una red puente (bridge) compartida
- Verificaciones de estado (healthchecks) donde sea apropiado
- Fija la versión de la imagen usando la etiqueta + el hash de índice (digest)
```

Claude buscará las imágenes a través de MCP, inspeccionará el directorio `app` y generará un archivo de Compose que monta y ejecuta tu código local.

---

## 8. Guardar el archivo de Docker Compose generado

Dile a Claude:

```console
Guarda el archivo de Docker Compose final (docker-compose.yaml) en el directorio del proyecto actual.
```

Deberías ver algo como esto:

```yaml
services:
  app:
    image: node:<tag>
    working_dir: /usr/src/app
    volumes:
      - .:/usr/src/app
    ports:
      - "3000:3000"
    depends_on:
      - db
    networks:
      - app-net

  db:
    image: postgres:18
    environment:
      POSTGRES_USER: example
      POSTGRES_PASSWORD: example
      POSTGRES_DB: appdb
    volumes:
      - db-data:/var/lib/postgresql
    ports:
      - "5432:5432"
    networks:
      - app-net

volumes:
  db-data:

networks:
  app-net:
    driver: bridge
```

---

## 9. Ejecutar el stack de Docker Compose

Desde la raíz de tu proyecto:

```console
$ docker compose up
```

Docker hará lo siguiente:

- Descargará (pull) las imágenes de Node y Postgres seleccionadas a través del MCP de Docker Hub
- Creará las redes y los volúmenes
- Iniciará los contenedores

Abre tu navegador en:

```console
http://localhost:3000
```

![Local Host](/guides/genai-claude-code-mcp/Images/Localhost.avif)

Tu aplicación de Node.js debería estar ejecutándose.

---

## Conclusión

Al combinar Claude Code con Docker MCP Toolkit, Docker Desktop y el servidor MCP de Docker Hub, puedes describir tu stack en lenguaje natural y dejar que MCP se encargue de los detalles. Esto elimina el cambio de contexto y lo reemplaza con un flujo de trabajo fluido y guiado por integraciones del protocolo de contexto de modelo.

---

### Siguientes pasos

- Explora los más de 220 servidores MCP disponibles en el [catálogo de MCP de Docker](https://hub.docker.com/mcp)
- Conecta Claude Code a tus bases de datos, API internas y herramientas de equipo
- Comparte tu configuración de MCP con tu equipo para que todos trabajen de manera consistente

El futuro del desarrollo no consiste en cambiar entre herramientas. Consiste en que las herramientas funcionen juntas de manera segura y predecible. Docker MCP Toolkit trae ese futuro a tu flujo de trabajo diario.

## Más información

- **[Explora el catálogo de MCP](https://hub.docker.com/mcp):** Descubre servidores MCP en contenedores y con seguridad reforzada
- **[Primeros pasos con MCP Toolkit en Docker Desktop](https://hub.docker.com/open-desktop?url=https://open.docker.com/dashboard/mcp):** Requiere la versión 4.48 o más reciente para iniciarse automáticamente
- **[Lee la serie de historias de terror de MCP](https://www.docker.com/blog/mcp-horror-stories-the-supply-chain-attack/):** Conoce los riesgos de seguridad comunes de MCP y cómo evitarlos