gpt-image-mcp

Dale a Claude Code el superpoder de generar imágenes. Di "dibújame una imagen", y Claude Code la generará directamente en tu conversación usando gpt-image-2 de OpenAI — sin necesidad de cambiar de aplicación ni copiar prompts.

🎯 ¿Qué es esto?

Para usuarios de Claude Code: este proyecto integra la generación de imágenes gpt-image-2 directamente en Claude Code como servidor MCP. Instala una vez, registra una vez, y Claude Code obtiene una capacidad nativa generate_image: describes la imagen en lenguaje natural (en cualquier idioma), y Claude Code genera el prompt, llama a gpt-image-2 y te entrega un PNG local. Si alguna vez has querido que Claude "simplemente lo dibuje" en lugar de explicarlo, esta es la pieza que faltaba.

También funciona como CLI independiente y con cualquier otro host MCP: el mismo núcleo, en todas partes.

No se necesita suscripción a ChatGPT Plus — solo una clave de API compatible con gpt-image-2.

Flujo de trabajo:

You: "A cyberpunk orange tabby cat in a spacesuit, starfield, cinematic lighting"
  ↓  Claude Code optimizes your prompt into professional English (automatic)
  ↓  gpt-image-mcp calls OpenAI gpt-image-2
  ↓  PNG saved locally → absolute path returned
You: got your image ✓

Related MCP server: gpt-image-mcp

✨ Características

• Integración nativa con Claude Code. Regístrate una vez y Claude Code obtiene una herramienta real generate_image: describe cualquier escena en lenguaje natural y recibe un PNG local en tu chat.

• Dos puntos de entrada, un mismo núcleo. La misma lógica de generación impulsa tanto un servidor MCP como una CLI simple.

  • gpt-image-mcp --mcp → servidor MCP stdio con herramientas generate_image / list_images

  • gpt-image-mcp "a cat in a spacesuit" → generación CLI de un solo uso

• Cualquier backend compatible con OpenAI. Apunta OPENAI_BASE_URL a donde quieras (revendedores, proxies, pasarelas autoalojadas).

• Niveles de calidad que se asignan al control low / medium / high de gpt-image-2. Sin modelos adicionales, sin sorpresas de coste.

• Las claves nunca están en el código. Todo se gestiona mediante variables de entorno: los secretos no entran en tu repositorio.

• Seguro con asincronía. Las imágenes se transmiten a disco como PNG decodificados en base64 localmente; la API nunca escribe en tu disco por ti.

🧰 Requisitos

• Python 3.10+

• Una clave de API de OpenAI, o un endpoint compatible con OpenAI (revendedor / pasarela / autoalojado) que sirva gpt-image-2 (o un modelo compatible que configures mediante GPT_IMAGE_MODEL).

• Python instalable mediante pip o uv.

📦 Instalación

Desde PyPI

pip install gpt-image-mcp           # pip
# or
uv tool install gpt-image-mcp       # uv

Desde el código fuente

git clone https://github.com/Garfield-Wuu/gpt-image-mcp
cd gpt-image-mcp
python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install -e .

⚙️ Configuración

Toda la configuración se realiza mediante variables de entorno:

Consejo: La URL base por defecto es el endpoint oficial de OpenAI. Para usar un revendedor o proxy, simplemente establece OPENAI_BASE_URL en su raíz /v1; nada más cambia.

🚀 Uso

Como servidor MCP (Claude Code)

Registra el servidor (sustituye ~/.venv por la ruta real de tu entorno):

claude mcp add gpt-image -s user \
  --env OPENAI_API_KEY="$OPENAI_API_KEY" \
  --env OPENAI_BASE_URL="$OPENAI_BASE_URL" \
  --env GPT_IMAGE_OUT="$PWD/out" \
  -- gpt-image-mcp --mcp

Reinicia Claude Code y dos herramientas estarán disponibles:

• generate_image — genera una imagen y guárdala localmente.

  ┌─────────────────────────────────────────────────────────────┐
  │ "A cyberpunk orange tabby cat in a spacesuit …"             │
  │    → gpt-image-mcp → local PNG → absolute path returned    │
  └─────────────────────────────────────────────────────────────┘

  Parámetros: prompt (obligatorio), size, quality, out_name.

• list_images — lista los PNG generados anteriormente (los más recientes primero).

Qué decirle a Claude Code:

"Dibuja un gato atigrado naranja ciberpunk con traje espacial, campo de estrellas, cinematográfico, alta calidad." → desencadena generate_image

"Genera una toma principal horizontal 1536x1024: ciudad ciberpunk bajo la lluvia, reflejos de neón." → establece tamaño + calidad

"¿Qué imágenes he generado antes?" → desencadena list_images

No se necesita ninguna sintaxis mágica: solo describe la imagen con tus propias palabras, en cualquier idioma. Claude Code se encarga del resto.

Como CLI

export OPENAI_API_KEY="sk-..."
gpt-image-mcp "a cyberpunk orange tabby cat, neon rain, cinematic" \
  --size 1536x1024 --quality high --out ./out/hero.png

Sin --no-interactive, la CLI te permite elegir tamaño/calidad de forma interactiva cuando hay un TTY presente.

🖼️ Parámetros

size — orientación del lienzo:

quality — el control de calidad propio de gpt-image-2 (modelo único; la compensación es velocidad/coste frente a detalle):

🛠️ Desarrollo

pip install -e ".[dev]"
ruff check .            # lint
pytest                  # run tests
python -m build         # build sdist + wheel

Estructura:

src/gpt_image_mcp/
├── img_core.py    # shared generation logic (no MCP dependency)
├── mcp_server.py  # FastMCP server: generate_image / list_images
└── __main__.py    # CLI + MCP entrypoints

🔐 Seguridad

• Tu clave de API nunca está incrustada en este paquete. Se lee de OPENAI_API_KEY en el momento de la llamada.

• No se registra ni se transmite nada más allá de la única solicitud de generación de imágenes.

• Los directorios .env y out/ están ignorados por Git de forma predeterminada.

📝 Notas y advertencias

• Cada solicitud suele tardar ~10–60 s según el endpoint y el nivel de calidad.

• Este proyecto no está afiliado a OpenAI; es un envoltorio MCP independiente.

• gpt-image-2 devuelve imágenes en base64 por defecto, que esta herramienta decodifica y escribe localmente en disco. También se gestiona un respaldo mediante url.

📄 Licencia

MIT © Garfield-Wuu.

⭐ Soporte

Si esto te ha ahorrado un dolor de cabeza, se agradece una estrella. Los issues y PRs son bienvenidos.

🌐 Otros idiomas / 其他语言

• 中文版 README (README.zh-CN.md) — 简体中文