GPT Image Playground MCP

Permite que tu agente use GPT Image Playground a través del navegador.

No es necesario modificar el código fuente de Playground. Tras instalar la extensión del navegador y completar la configuración de conexión una vez, el agente puede enviar tareas de generación de imágenes, consultar el progreso de las tareas y guardar las imágenes originales generadas en tu máquina local.

Este proyecto se basa en CookSleep/gpt_image_playground para las capacidades básicas de la página de Playground. Este proyecto proporciona un puente MCP para las operaciones visibles en la página y no incluye ni modifica el código fuente de Playground.

[!NOTE] Playground sigue siendo responsable de llamar a la API de imágenes y de gestionar su propio estado de inicio de sesión. Esta herramienta solo se encarga de transmitir tareas y operar la página.

Cómo puedes usarlo

• Hacer que el agente genere una imagen a partir de una descripción;

• Consultar si una tarea ya se ha completado;

• Descargar la imagen original de una tarea específica;

• Permitir que varios agentes compartan la misma cola de tareas del navegador;

• Usar imágenes de referencia locales en la generación.

Las herramientas MCP correspondientes son: generate_image, get_task_status y download_image.

Related MCP server: openai-gpt-image-1-mcp

Cómo funciona

Agent
  -> MCP stdio
  -> 本机桥接服务
  -> Chromium 扩展
  -> Playground 页面
  -> 生成并返回图片

Las tareas se procesan una a una por el servicio de puente local en el orden en que se envían. La generación de imágenes no tiene un plazo fijo de 20 segundos; después de que la extensión toma una tarea, espera continuamente a que la página termine y mantiene el estado de conexión. El tiempo de generación de diferentes imágenes puede variar, y esto no provoca que las tareas se envíen duplicadas o se reordenen automáticamente.

Después de cerrar el navegador, las tareas de la página no pueden continuar ejecutándose. Tras volver a abrir el navegador, consulta primero el estado de las tareas originales antes de decidir si envías nuevas tareas.

Antes de empezar

Prepara lo siguiente:

• Node.js 18 o superior;

• Chrome, Chromium u otro navegador Chromium compatible con Manifest V3;

• Una página del navegador que pueda abrir GPT Image Playground correctamente;

• Un cliente de agente compatible con MCP.

Inicio rápido

1. Obtener y compilar el proyecto

Obtén el proyecto desde GitHub:

git clone https://github.com/PEKI7483/image-playground-mcp.git
cd image-playground-mcp
npm install
npm run build

Si colocas el proyecto en otro directorio, <directorio raíz del proyecto> en el resto del documento se refiere al directorio image-playground-mcp clonado.

Una vez completada la compilación, el directorio dist/ debe contener server.js, bridge.js y bridgeMain.js.

2. Generar el código de conexión

El código de conexión se usa para proteger el servicio de puente local; no es una API Key de Playground. Genera un código de conexión aleatorio y guárdalo de forma segura:

node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"

La extensión y cada cliente de agente deben usar el mismo código de conexión. No envíes el código de conexión a repositorios de código ni a registros públicos.

La dirección de puente predeterminada es http://127.0.0.1:8787. Si el puerto ya está en uso, puedes usar otro puerto, por ejemplo 8790, pero la extensión y todos los agentes deben usar el mismo.

3. Instalar la extensión del navegador

1. Abre Chrome o Chromium y visita chrome://extensions.

2. Activa el «Modo de desarrollador» en la esquina superior derecha.

3. Haz clic en «Cargar extensión sin empaquetar».

4. Selecciona:

   <项目根目录>/extension

5. Haz clic en el icono de la extensión en la barra de herramientas del navegador para abrir la ventana de la extensión.

6. Haz clic en «Configuración de conexión» en la parte superior.

7. Establece «Dirección de la herramienta de imágenes» en http://127.0.0.1:8787 y «Código de conexión» en el código de conexión que acabas de generar.

8. Haz clic en «Guardar y comprobar». Cuando la conexión se establezca correctamente, la ventana volverá a «Resumen de ejecución».

El proceso de configuración se realiza solo dentro de la ventana de la extensión y no abre nuevas pestañas. La extensión guarda la dirección del puente y el código de conexión, pero no guarda la API Key de Playground.

4. Elige tu agente

Completa primero la configuración de la extensión y luego elige el método correspondiente al agente que uses. Todos los agentes pueden compartir un mismo servicio de puente, pero deben usar el mismo código de conexión y puerto.

Codex CLI y la aplicación Codex

Codex CLI, la aplicación Codex y la extensión del IDE comparten la configuración MCP. Reemplaza <directorio raíz del proyecto> y el código de conexión con los valores reales y ejecuta:

codex mcp add gpt-image-playground \
  --env MCP_BRIDGE_TOKEN=替换为连接码 \
  --env MCP_BRIDGE_PORT=8787 \
  -- node "<项目根目录>/dist/server.js"

Comprueba la configuración:

codex mcp list

Consulta la documentación oficial de Codex MCP para más opciones.

Claude Code

claude mcp add --transport stdio gpt-image-playground \
  --env MCP_BRIDGE_TOKEN=替换为连接码 \
  --env MCP_BRIDGE_PORT=8787 \
  -- node "<项目根目录>/dist/server.js"

Gemini CLI

Gemini CLI normalmente configura los servicios locales a través del archivo de configuración MCP. Añade el siguiente contenido a mcpServers en su settings.json:

{
  "gpt-image-playground": {
    "command": "node",
    "args": ["<项目根目录>/dist/server.js"],
    "env": {
      "MCP_BRIDGE_TOKEN": "替换为连接码",
      "MCP_BRIDGE_PORT": "8787"
    }
  }
}

Cursor, Cline, Roo Code, Windsurf y Claude Desktop

Estos clientes pueden añadir un servicio STDIO local en la página de configuración MCP, o editar la configuración JSON correspondiente. Fusiona el objeto gpt-image-playground siguiente en el mcpServers existente y conserva las demás configuraciones de servidores:

{
  "gpt-image-playground": {
    "command": "node",
    "args": ["<项目根目录>/dist/server.js"],
    "env": {
      "MCP_BRIDGE_TOKEN": "替换为连接码",
      "MCP_BRIDGE_PORT": "8787"
    }
  }
}

Las ubicaciones habituales son:

• Cursor: .cursor/mcp.json en el directorio del proyecto, o Cursor Settings > MCP;

• Cline: la página MCP Servers en la extensión;

• Roo Code: la página MCP Servers en la extensión;

• Windsurf: la página de configuración MCP o su archivo de configuración MCP;

• Claude Desktop: mcpServers en claude_desktop_config.json.

Después de guardar, reinicia el cliente o vuelve a cargar la configuración MCP.

Cuando el cliente MCP inicia dist/server.js, proporciona el protocolo MCP a través de stdio y, al mismo tiempo, inicia el servicio de puente local. Normalmente no es necesario ejecutar npm start manualmente.

Iniciar y confirmar la conexión

1. Abre GPT Image Playground y mantén abierta la página en modo galería normal.

2. Confirma que el campo de entrada de la descripción y el control de carga de imágenes son visibles en la página.

3. Inicia o reinicia el cliente de agente para que cargue la configuración MCP que acabas de crear.

4. Haz clic en el icono de la extensión en la barra de herramientas del navegador.

5. En «Resumen de ejecución», confirma que el servicio de puente, la conexión de la extensión y la página de Playground están en estado normal.

También puedes usar el endpoint de comprobación de estado para confirmar la conexión:

curl -H 'X-MCP-Bridge-Token: 替换为连接码' \
  http://127.0.0.1:8787/v1/health

Ejemplo de estado de salud:

{
  "bridge": "running",
  "extensionConnected": true,
  "playgroundTabCount": 1,
  "queueLength": 0
}

Ejemplos de uso

Generar una imagen

Llama a generate_image y pasa al menos una descripción:

{
  "prompt": "一只戴红色围巾的橘猫，工作室摄影风格"
}

La herramienta espera a que la página termine y no usa 20 segundos como plazo de finalización. Varios agentes pueden conectarse a la misma dirección de puente al mismo tiempo; las tareas entran en la misma cola FIFO y se ejecutan una a una.

Usar imágenes de referencia

Las imágenes de referencia se pueden pasar directamente a través de los parámetros MCP, sin necesidad de hacer clic manualmente en el control de carga de Playground:

{
  "prompt": "保留参考图的构图，改成水彩插画",
  "reference_image_paths": [
    "/absolute/path/reference.png",
    "/absolute/path/style.jpg"
  ]
}

Se admiten PNG, JPEG/JPG, WebP, GIF y AVIF; hasta 16 imágenes, cada una de no más de 8 MiB y un tamaño total de no más de 24 MiB. Después de que el servicio MCP lee estos archivos locales, la extensión inyecta el control de carga de múltiples archivos existente en Playground; el procesamiento de imágenes lo sigue realizando la página de Playground.

Descargar el resultado generado

Después de que generate_image tenga éxito, usa el task_id devuelto para llamar a download_image:

{
  "task_id": "上一步返回的 task_id",
  "output_path": "/absolute/path/generated.png",
  "image_index": 0
}

output_path debe ser una ruta absoluta. Un archivo existente solo se sobrescribe de forma idempotente si el contenido es exactamente el mismo; si el contenido es diferente, la herramienta avisará de un conflicto y no sobrescribirá el archivo original.

La imagen original en el diálogo de detalles puede cargarse más tarde que la miniatura de la tarjeta de tarea. La extensión es compatible con imágenes img normales, espera hasta 60 segundos y cierra el diálogo de detalles después de que la descarga se complete o falle.

Seguridad y privacidad

[!IMPORTANT] Tu estado de inicio de sesión y tu API Key de Playground siguen siendo gestionados por Playground. Esta herramienta solo opera en la página y no lee ni guarda cookies, localStorage, IndexedDB, variables JavaScript de la página ni claves de las respuestas de la API.

• El código de conexión solo se usa para proteger la interfaz de puente local; no es una API Key de Playground;

• El servicio de puente solo escucha en la dirección de bucle local por defecto;

• La generación de imágenes se realiza a través de la página visible de Playground y no llama directamente a la API de imágenes;

• Las imágenes de referencia las lee el servicio MCP y se entregan a la página de Playground para su procesamiento;

• Varios agentes pueden compartir el servicio, pero deben usar el mismo código de conexión y puerto.

Preguntas frecuentes

La extensión muestra «Servicio inaccesible»

Comprueba lo siguiente en este orden:

1. ¿El cliente de agente ya se ha iniciado y ha cargado dist/server.js?

2. ¿La dirección de puente en la extensión es http://127.0.0.1:8787?

3. ¿El código de conexión en la extensión coincide exactamente con la configuración del agente?

4. Después de modificar el código de la extensión, ¿has hecho clic en «Recargar» en chrome://extensions?

5. ¿Ya has abierto la página de galería normal de GPT Image Playground?

Si la conexión sigue sin establecerse, usa el comando de comprobación de estado anterior y conserva el resultado devuelto para facilitar un diagnóstico posterior.

El número de páginas de Playground es 0

Abre la página en modo galería normal de GPT Image Playground y confirma que el campo de entrada de la descripción es visible. La extensión no funciona llamando directamente a la API de imágenes y no procesa páginas que no tengan los controles de página correspondientes.

El tiempo de generación es largo y el agente parece no responder

El tiempo de generación de imágenes varía según la descripción, las imágenes de referencia y el estado de la página. Consulta primero las tarjetas de tareas de Playground y el resumen de ejecución de la extensión; no hagas clic repetidamente en generar. Las tareas ya tomadas seguirán esperando a que la página termine; si es necesario, puedes consultar con get_task_status.

Las imágenes de referencia no aparecen

Confirma lo siguiente:

• La ruta del archivo es una ruta absoluta;

• El formato del archivo es compatible;

• Cada imagen no supera los 8 MiB y el tamaño total no supera los 24 MiB;

• El número de imágenes no supera las 16;

• El control de carga de múltiples archivos existe en la página de Playground.

Fallo al descargar la imagen original

Confirma primero que la tarea se ha completado y que la tarjeta de tarea sigue visible, y usa una nueva ruta de salida absoluta. La descarga lee la imagen original del diálogo de detalles y no lee imágenes del almacenamiento del navegador.

Opciones de configuración

Si necesitas iniciar el servicio de puente por separado para depurar, puedes usar:

MCP_BRIDGE_TOKEN='替换为连接码' MCP_BRIDGE_PORT=8787 npm run bridge

Normalmente no es necesario ejecutar este comando manualmente. Cuando el cliente MCP inicia dist/server.js, también inicia el servicio de puente local.

Comentarios y ayuda

Si encuentras algún problema, no dudes en enviar un Issue. Para ayudarnos a entender la situación más rápido, incluye también:

• El cliente de agente utilizado y su versión;

• El navegador y su versión;

• El estado en el resumen de ejecución de la extensión;

• El resultado devuelto por el endpoint de comprobación de estado;

• Los mensajes de error de las tareas relacionadas.

Antes de compartir registros, elimina el código de conexión, las rutas personales y otra información sensible.

Límites de diseño

• Este proyecto no modifica el código fuente de GPT Image Playground;

• La API Key permanece en la sesión del navegador de Playground; MCP y la extensión no la leen;

• Las tareas solo se sirven a través de la dirección de bucle local y requieren un código de conexión;

• Después de cerrar el navegador, las tareas de la página no pueden continuar ejecutándose;

• Las tareas se procesan en serie para evitar que varios agentes operen la misma página de Playground al mismo tiempo.

Gracias por dedicar tiempo a probar esta herramienta. Esperamos que haga que la generación de imágenes sea más fluida y que la colaboración entre el agente y Playground sea más natural.