Image Generator

Generador de Imágenes MCP 🍌

Genera y edita imágenes desde Cursor, Claude Code, Codex, o cualquier herramienta compatible con MCP. Compatible con Google Gemini, OpenAI GPT Image y BytePlus Seedream.

Este servidor MCP convierte una solicitud en lenguaje natural en un archivo de imagen. Añade detalles fotográficos relevantes como iluminación, ángulo de cámara, materiales y paleta, y luego devuelve la imagen guardada como un recurso MCP.

Cómo Funciona

You: "a roast chicken for a recipe page, partway through
      carving so you can see how juicy it is"
        ↓
  Your AI assistant sends the request to mcp-image
        ↓
  Prompt enhancement adds relevant photographic details
  (subject, lighting, camera, and palette)
        ↓
  The selected provider generates the image
  (using the configured grounding, consistency, and resolution options)
        ↓
  Saved file, returned as an MCP resource

Tu asistente de IA proporciona el estilo, propósito y contexto de tu solicitud. mcp-image completa los detalles visuales faltantes y selecciona la configuración de generación.

El optimizador de prompts utiliza un marco de Sujeto–Contexto–Estilo. Se ejecuta en Gemini 2.5 Flash por defecto, OpenAI Responses cuando IMAGE_PROVIDER=openai, o ModelArk Responses cuando IMAGE_PROVIDER=seedream. Añade detalles faltantes sobre el sujeto, entorno, iluminación y trabajo de cámara, manteniendo los detalles ya presentes en la solicitud. Los prompts detallados reciben menos cambios.

Ejemplo

Tú escribes: "una foto de una cena de pollo asado para un sitio de recetas. debería parecer que realmente fue cocinado, y debería estar parcialmente cortado para que se note lo jugoso que es"

Lo que el servidor envía al modelo de imagen: "...un pollo entero bellamente asado, dorado y brillante, descansando sobre una tabla de cortar de madera rústica. Una pierna está parcialmente cortada, revelando carne blanca tierna y suculenta con jugos ricos y brillantes acumulándose alrededor del cuchillo de trinchar ... poca profundidad de campo para mantener el enfoque nítidamente en el pollo cortado."

Proveedor Gemini, preset predeterminado fast.

Lo que se mantuvo:

• for a recipe site → un solo sujeto, con todo lo demás mantenido subordinado
• actually cooked → jugos extendidos por la tabla, dorado desigual
• partway through being carved → la cara del corte, con rebanadas colocadas a su lado
• how juicy it is → encuadre cercano y poca profundidad de campo en el corte

La misma solicitud y configuración, sin optimización de prompts

Establece SKIP_PROMPT_ENHANCEMENT=true para enviar tu prompt sin cambios.

Características

• Mejora de prompts: Añade detalles de iluminación, composición, cámara y paleta utilizando el modelo de texto del proveedor seleccionado.
• Proveedores de imagen: Establece IMAGE_PROVIDER=openai para OpenAI GPT Image o IMAGE_PROVIDER=seedream para BytePlus Seedream a través de ModelArk. Pasa provider en una solicitud individual para cambiar de proveedor sin modificar la configuración del servidor.
• Presets de calidad: Selecciona fast, balanced o quality. Cada proveedor mapea estos valores a una ruta de modelo compatible. Ver Presets de Calidad.
• Edición de imágenes: Edita una imagen existente con instrucciones en lenguaje natural manteniendo su estilo y detalles visuales.
• Controles de resolución: Solicita hasta 4K, dependiendo del proveedor y la ruta de calidad.
• Relaciones de aspecto: Compatible con formatos desde cuadrado (1:1) hasta ultra ancho (21:9) y ultra alto (1:8).
• Consistencia de personajes: Mantén la apariencia de un personaje consistente en guiones gráficos, tomas de producto o series de imágenes.
• Opciones específicas del proveedor:
  • Fundamentación de búsqueda de Google para precisión fáctica en tiempo real con el proveedor Gemini
  • Conocimiento mundial para representaciones fotorrealistas de figuras históricas, lugares emblemáticos y escenarios fácticos
  • Guía de combinación a nivel de prompt para escenas compuestas
  • Generación consciente del propósito (por ejemplo, "portada de libro de cocina" produce resultados diferentes que "publicación en redes sociales")
• Formatos de salida: OpenAI y Seedream admiten selección de PNG o JPEG a través del nombre del archivo de salida.

Requisitos Previos

• Node.js 22 o superior
• Clave API de Gemini - Obtén la tuya en Google AI Studio para el proveedor Gemini predeterminado
• Clave API de OpenAI - Obtén la tuya en OpenAI cuando uses IMAGE_PROVIDER=openai
• Clave API de BytePlus ModelArk - Crea una en la consola de ModelArk región AP cuando uses IMAGE_PROVIDER=seedream
• Una herramienta de IA compatible con MCP: Cursor, Claude Code, Codex u otras
• Conocimientos básicos de terminal/línea de comandos

Inicio Rápido

1. Obtén tu Clave API de Gemini

Obtén tu clave API en Google AI Studio

Para usar OpenAI en su lugar, obtén una clave API de OpenAI y establece:

IMAGE_PROVIDER=openai
OPENAI_API_KEY=your_openai_api_key_here

El modo OpenAI requiere verificación de organización. Consulta Uso del proveedor OpenAI para detalles de configuración y diferencias de características.

Para usar BytePlus Seedream en su lugar, crea una clave API en la región AP de ModelArk y establece:

IMAGE_PROVIDER=seedream
ARK_API_KEY=<your-api-key>

Consulta Uso del proveedor BytePlus Seedream para detalles de compatibilidad.

2. Configuración MCP

Para Codex

Añade a ~/.codex/config.toml:

[mcp_servers.mcp-image]
command = "npx"
args = ["-y", "mcp-image"]

[mcp_servers.mcp-image.env]
GEMINI_API_KEY = "your_gemini_api_key_here"
IMAGE_OUTPUT_DIR = "/absolute/path/to/images"

Para OpenAI GPT Image desde un fork local:

[mcp_servers.mcp-image]
command = "node"
args = ["/absolute/path/to/mcp-image/dist/index.js"]

[mcp_servers.mcp-image.env]
IMAGE_PROVIDER = "openai"
OPENAI_API_KEY = "your_openai_api_key_here"
IMAGE_OUTPUT_DIR = "/absolute/path/to/images"

Para Cursor

Añade a la configuración de Cursor:

• Global (todos los proyectos): ~/.cursor/mcp.json
• Específico del proyecto: .cursor/mcp.json en la raíz de tu proyecto

{
  "mcpServers": {
    "mcp-image": {
      "command": "npx",
      "args": ["-y", "mcp-image"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here",
        "IMAGE_OUTPUT_DIR": "/absolute/path/to/images"
      }
    }
  }
}

Para OpenAI GPT Image desde un fork local:

{
  "mcpServers": {
    "mcp-image": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-image/dist/index.js"],
      "env": {
        "IMAGE_PROVIDER": "openai",
        "OPENAI_API_KEY": "your_openai_api_key_here",
        "IMAGE_OUTPUT_DIR": "/absolute/path/to/images"
      }
    }
  }
}

Para Claude Code

Ejecuta en el directorio de tu proyecto para habilitarlo para ese proyecto:

cd /path/to/your/project
claude mcp add mcp-image --env GEMINI_API_KEY=your-api-key --env IMAGE_OUTPUT_DIR=/absolute/path/to/images -- npx -y mcp-image

O añádelo globalmente para todos los proyectos:

claude mcp add mcp-image --scope user --env GEMINI_API_KEY=your-api-key --env IMAGE_OUTPUT_DIR=/absolute/path/to/images -- npx -y mcp-image

Para OpenAI GPT Image desde un fork local:

npm install
npm run build
claude mcp add mcp-image --scope user \
  --env IMAGE_PROVIDER=openai \
  --env OPENAI_API_KEY=your-openai-api-key \
  --env IMAGE_OUTPUT_DIR=/absolute/path/to/images \
  -- node /absolute/path/to/mcp-image/dist/index.js

Seguridad: Nunca comprometas claves API al control de versiones. Utiliza configuración específica del entorno.

Requisitos de ruta:

• IMAGE_OUTPUT_DIR debe ser una ruta absoluta (por ejemplo, /Users/username/images, no ./images)
• El valor predeterminado es ./output en el directorio de trabajo actual si no se especifica
• El directorio se creará automáticamente si no existe

Presets de Calidad

Los presets equilibran velocidad, calidad y costo:

Preset	Modelo	Mejor para	Velocidad
fast (predeterminado)	Nano Banana 2 (Gemini 3.1 Flash Image)	Iteraciones rápidas, borradores, generación de alto volumen	~30–40s
balanced	Nano Banana 2 + Pensamiento	Imágenes de producción, buena calidad con velocidad razonable	Media
quality	Nano Banana Pro (Gemini 3 Pro Image)	Entregables finales, máxima fidelidad, visuales críticos	Lenta

Establece el valor predeterminado mediante la variable de entorno IMAGE_QUALITY:

IMAGE_QUALITY=fast       # (default) Fastest generation
IMAGE_QUALITY=balanced   # Enhanced thinking for better quality
IMAGE_QUALITY=quality    # Maximum quality output

Para anular el preset en una solicitud, dile a tu asistente de IA que "genere en alta calidad" o "use calidad equilibrada". El asistente pasa el parámetro quality correspondiente.

Codex:

[mcp_servers.mcp-image.env]
GEMINI_API_KEY = "your_gemini_api_key_here"
IMAGE_QUALITY = "balanced"

Cursor: Añade "IMAGE_QUALITY": "balanced" a la sección de entorno en tu configuración.

Claude Code:

claude mcp add mcp-image --env GEMINI_API_KEY=your-api-key --env IMAGE_QUALITY=balanced --env IMAGE_OUTPUT_DIR=/absolute/path/to/images -- npx -y mcp-image

Omitir Mejora de Prompts

Establece SKIP_PROMPT_ENHANCEMENT=true para enviar prompts directamente al generador de imágenes. Úsalo cuando la redacción exacta del prompt deba permanecer sin cambios.

Configuración del Proveedor

Variable	Predeterminado	Descripción
IMAGE_PROVIDER	gemini	gemini, openai o seedream. Se usa cuando una solicitud no establece provider
GEMINI_API_KEY	-	Requerida para usar el proveedor gemini
OPENAI_API_KEY	-	Requerida para usar el proveedor openai
ARK_API_KEY	-	Requerida para usar el proveedor seedream; usa una clave de la región AP de ModelArk

Un provider a nivel de solicitud tiene prioridad sobre IMAGE_PROVIDER; si ninguno está establecido, se usa gemini. El servidor puede iniciarse sin claves API, pero generate_image requiere una clave para el proveedor seleccionado. Si falta una clave, el error identifica la variable de entorno a configurar.

Uso del proveedor BytePlus Seedream

A partir del 29 de julio de 2026, Seedream 5.0 Pro está disponible solo en ModelArk AP (ap-southeast-1). Crea una clave API en la consola de la región AP de ModelArk.

mcp-image usa seed-2-0-lite-260428 para la mejora de prompts y Seedream 5.0 Pro para la generación de imágenes. Estas elecciones de modelo son fijas por el servidor y no son configurables mediante variables de entorno.

El enrutamiento de calidad de Seedream es fijo:

Preset público	Ruta Seedream	Optimizador de imagen nativo	imageSize compatibles	Predeterminado cuando se omite
fast	Seedream 5.0 Pro	fast	1K, 2K	1K
balanced	Seedream 5.0 Pro	standard	1K, 2K	1K
quality	Seedream 5.0 Pro	standard	1K, 2K	1K

Todas las relaciones de aspecto compatibles usan BytePlus Method 1, por lo que las dimensiones finales en píxeles son seleccionadas por el modelo. Seedream rechaza imageSize: "4K" y useGoogleSearch: true. Las solicitudes de imagen tienen un tiempo de espera fijo de 300 segundos. La edición de imágenes de Seedream acepta solo imágenes de entrada PNG y JPEG.

Uso del proveedor OpenAI

Establece IMAGE_PROVIDER=openai para usar OpenAI tanto para la mejora de prompts como para la generación de imágenes. mcp-image actualmente usa gpt-5.4-nano para la mejora de prompts y gpt-image-2 para la generación de imágenes. Estas elecciones de modelo son fijas por el servidor y no son configurables mediante variables de entorno.

OpenAI puede requerir verificación de organización antes de permitir el acceso a gpt-image-2. Si la generación de imágenes falla con un error 403 de permiso o verificación, revisa la configuración de tu organización: https://platform.openai.com/settings/organization/general

Comportamiento del proveedor OpenAI:

• Admite generación de texto a imagen e imagen a imagen.
• Admite aspectRatio, mapeado al tamaño de imagen de OpenAI compatible más cercano.
• Admite valores imageSize: 1K, 2K y 4K.
• Mapea quality como fast -> low, balanced -> medium y quality -> high. Para cualquier cosa más allá de sujetos simples, se recomienda balanced o quality.
• No admite useGoogleSearch; esa opción solo está disponible con el proveedor Gemini.

La mejora de prompts utiliza una llamada separada a la API de OpenAI Responses. Establece SKIP_PROMPT_ENHANCEMENT=true para enviar prompts directamente al modelo de imagen.

Ejemplos de Uso

Una vez configurado, describe la imagen en lenguaje natural:

Generación Básica de Imágenes

"Generate a serene mountain landscape at sunset with a lake reflection"

La mejora de prompts completa los detalles relevantes sobre iluminación, materiales, composición y atmósfera.

Edición de Imágenes

"Edit this image to make the person face right"
(with inputImagePath: "/path/to/image.jpg")

Opciones de Generación

Consistencia de Personajes:

"Generate a portrait of a medieval knight, maintaining character consistency for future variations"
(with maintainCharacterConsistency: true)

Alta Resolución 4K con Renderizado de Texto:

"Generate a professional product photo of a smartphone with clear text on the screen"
(with imageSize: "4K")

Relación de Aspecto Personalizada:

"Generate a cinematic landscape of a desert at golden hour"
(with aspectRatio: "21:9")

Referencia de la API

Herramienta generate_image

El servidor utiliza un modelo separado para cada una de sus dos etapas:

1. Optimización de Prompts (Gemini 2.5 Flash por defecto, gpt-5.4-nano vía OpenAI Responses en modo OpenAI, o seed-2-0-lite-260428 vía ModelArk Responses en modo Seedream): Refina tu prompt usando el marco de Sujeto–Contexto–Estilo. Se puede omitir mediante SKIP_PROMPT_ENHANCEMENT.
2. Generación de Imágenes (Nano Banana 2/Pro por defecto, gpt-image-2 en modo OpenAI, o Seedream 5.0 Pro en modo Seedream): Crea la imagen final. Los mapeos de calidad específicos del proveedor se describen arriba.

Parámetros

Parámetro	Tipo	Requerido	Descripción
prompt	string	✅	Descripción de texto o instrucción de edición
quality	string	-	Preajuste de calidad: fast (predeterminado), balanced, quality. Anula la variable de entorno IMAGE_QUALITY para esta solicitud
provider	string	-	Proveedor de imágenes: gemini, openai, seedream. Anula la variable de entorno IMAGE_PROVIDER para esta solicitud; la clave API del proveedor debe estar configurada
inputImagePath	string	-	Ruta absoluta a la imagen de entrada para edición de imagen a imagen
fileName	string	-	.png, .jpg o .jpeg selecciona ese formato de salida para OpenAI/Seedream. Otros sufijos o la ausencia de estos usan el valor predeterminado del proveedor, y el nombre guardado se corrige a la extensión real de la imagen
aspectRatio	string	-	1:1 (predeterminado), 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 1:8, 4:1, 8:1
imageSize	string	-	1K, 2K, 4K. Déjalo sin especificar para calidad estándar
blendImages	boolean	-	Habilita la fusión de múltiples imágenes para combinar varios elementos visuales de forma natural
maintainCharacterConsistency	boolean	-	Mantiene la consistencia de la apariencia del personaje en diferentes poses y escenas
useWorldKnowledge	boolean	-	Usa conocimiento del mundo real para un contexto preciso (figuras históricas, lugares emblemáticos, escenarios fácticos)
useGoogleSearch	boolean	-	Habilita la fundamentación con Búsqueda de Google con Gemini. OpenAI y Seedream rechazan true
purpose	string	-	Uso previsto (p. ej., "portada de libro de cocina", "publicación en redes sociales"). Ayuda a adaptar el estilo visual y los detalles

Respuesta

{
  "type": "resource",
  "resource": {
    "uri": "file:///path/to/generated/image.png",
    "name": "image-filename.png",
    "mimeType": "image/png"
  },
  "metadata": {
    "model": "gemini-3.1-flash-image",
    "provider": "gemini",
    "processingTime": 5000,
    "timestamp": "2026-01-01T12:00:00.000Z"
  }
}

Solución de problemas

Problemas comunes

"Clave API no encontrada"

• Asegúrate de que GEMINI_API_KEY esté configurada al usar Gemini, OPENAI_API_KEY esté configurada cuando IMAGE_PROVIDER=openai, o ARK_API_KEY esté configurada cuando IMAGE_PROVIDER=seedream
• Verifica que la clave API sea válida y tenga permisos de generación de imágenes

"Archivo de imagen de entrada no encontrado"

• Usa rutas de archivo absolutas, no relativas
• Asegúrate de que el archivo exista y sea accesible
• Formatos compatibles: PNG, JPEG, WebP (máx. 10 MB)

"No se encontraron datos de imagen en la respuesta de la API de Gemini"

• Intenta reformular tu indicación con detalles más específicos
• Asegúrate de que tu indicación sea apropiada para la generación de imágenes
• Comprueba si tu clave API tiene cuota suficiente

Consejos de rendimiento

• En modo Gemini, el preajuste fast normalmente tarda ~30–40 segundos, incluida la optimización de la indicación
• En modo Gemini, balanced usa razonamiento adicional y quality selecciona Nano Banana Pro
• En modo Seedream, usa la tabla de rutas anterior; todos los niveles usan Pro, con fast seleccionando la optimización nativa de fast y balanced/quality seleccionando standard
• Alta resolución (2K/4K): el tiempo de procesamiento varía según el proveedor y la ruta
• Di para qué sirve la imagen; el optimizador proporciona los términos fotográficos que implica
• Los detalles que especifiques tú mismo se transmiten en lugar de reescribirse
• Considera useWorldKnowledge para temas históricos o fácticos
• Usa imageSize: "4K" cuando el proveedor seleccionado lo admita; Seedream acepta 1K y 2K

Notas de uso

• Este servidor MCP usa la API de Gemini de pago:
  • Optimización de indicaciones: Gemini 2.5 Flash (uso mínimo de tokens)
  • Generación de imágenes: el modelo depende del preajuste de calidad
    • fast / balanced: Nano Banana 2 (Gemini 3.1 Flash Image, menor costo)
    • quality: Nano Banana Pro (Gemini 3 Pro Image, mayor costo)
  • balanced usa tokens de razonamiento adicionales (costo ligeramente mayor que fast)
• Consulta los precios y límites de tarifa actuales en Google AI Studio
• Supervisa tu uso de la API para evitar cargos inesperados
• El paso de optimización de indicaciones agrega un costo mínimo y mantiene la intención de tu solicitud en la imagen generada

Habilidad de agente independiente: Guía de indicaciones para generación de imágenes

Este proyecto también incluye una Habilidad de agente independiente (SKILL.md). Úsala para ayudar a un asistente de IA a escribir indicaciones para una herramienta que ya admite generación de imágenes. La habilidad es independiente del servidor MCP, no lo llama y no requiere una clave API.

La habilidad cubre el marco Sujeto-Contexto-Estilo, iluminación, texturas, ángulos de cámara, consistencia de personajes, composición y edición de imágenes. Funciona con Gemini, GPT Image, Flux, Stable Diffusion, Midjourney y otros modelos de imagen.

Instalación

npx mcp-image skills install --path <skills-directory>

La habilidad se colocará en <skills-directory>/image-generation/SKILL.md. Por ejemplo: ~/.cursor/skills (Cursor), ~/.codex/skills (Codex) o ~/.claude/skills (Claude Code).

Licencia

Licencia MIT: consulta LICENSE para más detalles.

---

¿Necesitas ayuda? Abre un problema o consulta la sección de solución de problemas anterior.