image-gen-mcp

Servidor MCP multimodelo de generación de imágenes: OpenAI GPT Image y Google Gemini (Nano Banana) detrás de una sola herramienta, con caché por hash y respuesta por ruta de archivo (nunca base64).

Herramientas

| Tool | Qué hace | |---|---| | generate_image | Texto→imagen; con input_paths edita esas imágenes guiado por el prompt (hasta 14 referencias). Guarda el archivo en disco y devuelve { path, width, height, bytes, mime, model, cached, elapsedMs }. | | list_cache | Inventario del directorio de caché: { count, totalBytes, files[] }. | | clear_cache | Borra todo, o solo lo mayor a max_age_hours. |

Regla de diseño #1: nunca devuelve base64 al cliente — devolvería cientos de miles de tokens al contexto del agente que llama. Siempre ruta absoluta.

Modelos

| Modelo | Proveedor | Cuándo usarlo | Costo aprox. | |---|---|---|---| | gpt-image-2 | OpenAI | #1 texto→imagen (arenas ago-2026): texto dentro de la imagen, adherencia a prompts complejos, realismo. quality high para layouts densos de texto (lento, 30s+) | ~$0.02 (low 512) – $0.21 (high 1K) | | gpt-image-1.5 | OpenAI | Generación OpenAI previa: buen texto y edición, más barato/rápido que el 2 | ~$0.03–0.13 | | gpt-image-1-mini | OpenAI | Borradores baratos OpenAI | ~$0.005–0.04 | | gemini-3-pro-image | Google | Nano Banana Pro: calidad máxima Google, hasta 14 referencias | ~$0.13 | | gemini-3.1-flash-image | Google | Nano Banana 2: 4K nativo, edición multi-referencia consistente | ~$0.034–0.13 | | gemini-3.1-flash-lite-image | Google | El más barato/rápido para volumen y borradores | ~$0.034 | | gemini-2.5-flash-image | Google | Legacy | ~$0.04 |

Default: gemini-3-pro-image (configurable con IMAGE_GEN_MODEL).

Parámetros de generate_image

• prompt (requerido) — qué generar o cómo editar.
• model — ver tabla arriba. El proveedor se infiere del modelo.
• aspect_ratio — 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 1:8 8:1 1:4 4:1. OpenAI rechaza ratios más extremos que 1:3–3:1 (1:4, 4:1, 1:8, 8:1) — para esos usa un modelo Gemini.
• image_size — 512 (borradores), 1K (default), 2K, 4K. En OpenAI se mapea a un tamaño custom válido (múltiplos de 16, mín 655,360 px).
• quality — solo modelos OpenAI: low | medium (default) | high | auto. Rechazado explícitamente en modelos Google.
• input_paths — imágenes locales a editar (OpenAI acepta solo PNG/JPEG/WebP; Gemini además BMP/TIFF/GIF).
• no_cache — fuerza regeneración (el resultado igual se cachea).

Caché

sha256(model + aspect_ratio + image_size + quality + prompt + hash de cada input) → ~/.cache/image-gen-mcp/<hash32>.<ext>. Misma petición = cached: true, cero costo de API. Cambia el prompt, un input, el modelo o el quality y se regenera.

Variables de entorno

• GEMINI_API_KEY — requerida para modelos Google.
• OPENAI_API_KEY — requerida para modelos OpenAI (org verificada para gpt-image). Solo la del proveedor que invoques es necesaria.
• IMAGE_GEN_MODEL — modelo default (default: gemini-3-pro-image).
• IMAGE_GEN_CACHE_DIR — default ~/.cache/image-gen-mcp.

Registro (ZCode)

"image-gen": {
  "type": "stdio",
  "command": "node",
  "args": ["/home/angel/.zcode/cli/mcp-servers/image-gen/index.mjs"],
  "env": {
    "GEMINI_API_KEY": "...",
    "OPENAI_API_KEY": "..."
  },
  "timeoutMs": 90000
}

Con timeout holgado: gpt-image-2 en quality: high puede tardar 30-60s+.

Pruebas

GEMINI_API_KEY=... OPENAI_API_KEY=... node test-client.mjs

Matriz: rechazos de esquema (modelo/ratio/quality), generación real Gemini, cache hit, edición Gemini, generación real gpt-image-2 (low, barato), cache hit OpenAI, edición cruzada (imagen generada por Gemini editada por gpt-image-2), list_cache y clear_cache. Última corrida: 2026-08-24, todo en verde.