Plugin GPT Image 2 para Claude Desktop Code

Genera y edita imágenes de proyectos con OpenAI GPT Image 2 a través de un servidor MCP local empaquetado. El plugin escribe una imagen validada por llamada de pago, mantiene los archivos dentro de un espacio de trabajo de proyecto aprobado y nunca sobrescribe un destino existente.

简体中文

Superficie de Claude compatible

Este plugin es para Claude Desktop Code, la experiencia Code orientada a proyectos en la aplicación Claude Desktop. Claude Desktop Chat no es compatible. No es un paquete MCPB ni un servicio MCP remoto.

Related MCP server: mcp-openai-images-audio

Instalación a través de la interfaz gráfica de Claude Desktop Code

La instalación del plugin mediante la interfaz gráfica es la vía principal:

1. Abre el proyecto de destino en Claude Desktop Code.

2. Abre la sección Configuración → Plugins de la interfaz gráfica. Las etiquetas pueden variar ligeramente según la versión de Claude.

3. Añade la raíz de este repositorio como un mercado local o selecciona su fuente de repositorio, luego instala gpt-image-2@kpk-plugins.

4. Habilita el plugin instalado para el proyecto actual. La habilitación es específica del proyecto; instalarlo no otorga acceso automáticamente a todos los proyectos.

5. Abre la configuración del plugin para ajustarlo. No copies .mcp.json en la configuración ordinaria.

La raíz del plugin es la raíz del mercado, y la entrada del mercado apunta a ./.

Requisito de ejecución

El único requisito de ejecución es Node.js 20+, disponible en el PATH que ve Claude Desktop Code. El plugin instalado inicia directamente el dist/server.mjs precompilado. En tiempo de ejecución, el plugin no ejecuta npm, npx, scripts de ciclo de vida, compilación de código fuente ni carga node_modules.

La copia del mercado incluida contiene el paquete independiente. Una prueba de la copia instalada inicia solo los archivos rastreados por Git y verifica que get_status funcione sin un directorio node_modules presente y sin una clave API.

npm y las dependencias de desarrollo solo son necesarias para los colaboradores que compilan o prueban el código fuente.

Configuración en la interfaz gráfica

En la configuración del plugin, introduce la clave API en el campo sensible Clave API de OpenAI. No la coloques en una línea de comandos, .env, .mcp.json, configuración ordinaria, un README, un prompt o un registro, y no le pidas a Claude que la muestre o inspeccione.

La URL base oficial predeterminada es:

https://api.openai.com/v1

Una URL base personalizada recibe la clave API, los prompts y las imágenes de edición enviadas por este plugin. Configúrala solo cuando confíes en ese endpoint y su operador. Un endpoint personalizado debería incluir normalmente /v1; el plugin no lo añade automáticamente. El único ejemplo documentado para el usuario es:

https://api.example.invalid/v1

La URL debe ser una URL HTTP(S) absoluta sin credenciales, consulta, fragmento, caracteres de control ni espacios en blanco circundantes. Un endpoint compatible debe implementar la API de imágenes utilizada por el cliente de OpenAI; la compatibilidad no se implica simplemente por aceptar una URL.

HTTP está permitido para endpoints compatibles de confianza en redes locales o privadas, pero envía la clave API, los prompts y las imágenes de edición sin cifrado de transporte. Usa una URL Base http:// solo en una red y un endpoint de confianza; prefiere HTTPS en otros casos.

Ejecuta /gpt-image-2:setup después de la instalación. El comando solo llama a get_status y no realiza ninguna solicitud al proveedor.

Herramientas

get_status

Informa solo datos de estado seguros: booleano de clave API configurada, si hay una URL base personalizada configurada, base_url_valid: true para la URL activa de un servidor en ejecución, raíces de espacio de trabajo aprobadas, modelo, versión del servidor y el directorio de salida relativo predeterminado. Una URL base personalizada no válida impide el inicio del servidor; corrígela en la configuración del plugin y recarga o reinicia el plugin. get_status no realiza solicitudes al proveedor ni a la API de imágenes y nunca devuelve la clave ni el valor de la URL base.

generate_image

Genera una imagen con el modelo gpt-image-2, fijo n: 1, y guarda un nuevo archivo. Las entradas principales son:

• prompt

• quality: auto, low, medium o high

• size

• output_format: png, jpeg o webp

• output_compression opcional para JPEG/WebP de 0 a 100

• moderation: auto o low

• output_path relativo opcional y workspace_root aprobado

edit_image

Edita de una a ocho entradas de edición en el orden proporcionado y guarda una nueva imagen. Las entradas pueden ser PNG, JPEG o WebP. El límite es de 50 MiB por entrada y 200 MiB en total para todas las imágenes de edición más la máscara opcional.

Una máscara opcional debe ser un PNG con un canal alfa, coincidir con las dimensiones de la primera imagen de entrada y tener menos de 4 MiB. No se admiten fondos de salida transparentes; el alfa de la máscara solo identifica la región de edición.

Formatos, tamaños y salida

• Formatos de salida: PNG, JPEG y WebP.

• El tamaño predeterminado de la herramienta es 1024x1024. También se acepta auto.

• Un WIDTHxHEIGHT personalizado debe usar múltiplos de 16, cada lado debe tener como máximo 3840 píxeles, la relación de aspecto debe estar entre 1:3 y 3:1, y el total de píxeles debe estar entre 655,360 y 8,294,400.

• PNG no usa compresión de salida. JPEG y WebP aceptan valores de compresión de 0 a 100.

• Si se omite output_path, la salida se coloca en .claude/generated-images/gpt-image-2 con un nombre de archivo único sin prompt.

• Las rutas de salida explícitas se conservan, deben ser relativas a una raíz de espacio de trabajo aprobada y deben usar una extensión que coincida con el formato solicitado.

• Se rechazan los destinos existentes. La publicación sin sobrescritura también evita que llamadas concurrentes reemplacen el mismo destino.

Las dimensiones reales se conservan y se informan después de que la imagen guardada se decodifica y valida. Si un tamaño solicitado explícito difiere, el archivo se guarda con sus dimensiones reales y el resultado incluye SIZE_MISMATCH.

Las imágenes de 2 MiB o menos incluyen una vista previa en línea. Para imágenes más grandes, se omite la vista previa en línea; la ruta del archivo guardado sigue siendo la autorizada. TEMP_CLEANUP_PENDING significa que la salida se guardó correctamente, pero la limpieza de un archivo de publicación temporal aún está pendiente.

Costo, concurrencia y reintentos

La generación y edición son operaciones de pago al proveedor. El plugin fija una salida por solicitud y permite una llamada de pago a la vez en cada proceso del servidor. No hay reintentos del SDK ni reintentos de la aplicación, por lo que una llamada de pago fallida no se repite automáticamente. Confirma los prompts, las entradas de edición, el tamaño, el formato y la ruta de salida antes de invocar una herramienta de imagen.

Límite de espacio de trabajo y seguridad

• Las salidas permanecen dentro de una raíz de espacio de trabajo aprobada por Claude Desktop Code. Las rutas de salida no pueden ser absolutas ni salir de la raíz.

• Las rutas de entrada absolutas contenidas se aceptan solo cuando ya se resuelven dentro de una raíz aprobada; una ruta de entrada nunca otorga una nueva raíz.

• Los archivos de entrada se copian a través de identificadores estables en instantáneas temporales privadas antes de la carga. Los originales no se modifican.

• La salida del proveedor se decodifica estrictamente, se valida como imagen, se vacía y se publica con semántica de no sobrescritura.

• Los registros solo aceptan códigos de estado acotados y contexto numérico; se excluyen prompts, claves API, URL base, datos de imagen, Base64 y rutas de entrada completas.

Límite de Junction de Node 20 en Windows

En Windows con Node 20, se rechazan las escapatorias de reparse-point/Junction existentes, y las rutas padre de salida se vuelven a verificar inmediatamente antes de la publicación exclusiva. Un reemplazo activo del directorio por otro proceso con la misma autoridad entre las verificaciones permanece fuera del límite de amenaza. Se necesitaría un helper nativo basado en identificadores de Win32 para eliminar por completo esa condición de carrera de reemplazo por la misma autoridad.

Solución de problemas

• Clave API no configurada: abre la configuración del plugin de Claude Desktop Code y completa el campo sensible de la clave API. No pegues la clave en el chat ni en un shell.

• URL base personalizada no válida o no utilizada: una URL base personalizada no válida impide que el servidor se inicie. Corrígela en la configuración del plugin, confirma que el ajuste se haya guardado y luego recarga o reinicia el plugin. Los endpoints personalizados deberían terminar normalmente en /v1; no se añade ningún segmento /v1 automáticamente.

• Sin raíz de espacio de trabajo aprobada: abre el proyecto en Claude Desktop Code y habilita el plugin para ese proyecto.

• OUTPUT_EXISTS: elige una nueva ruta de salida relativa. El plugin no sobrescribirá.

• SIZE_MISMATCH: usa el ancho y alto reales devueltos; la imagen guardada es válida.

• Vista previa omitida: abre la ruta relativa o absoluta devuelta; las vistas previas en línea están limitadas a 2 MiB.

Compilación y prueba desde el código fuente

Los comandos de desarrollo pueden instalar y usar dependencias de desarrollo; no forman parte del comportamiento en tiempo de ejecución del plugin instalado. El comando de validación desactiva los hooks implícitos del ciclo de vida de npm antes de verificar que el conjunto de scripts aprobado sea exacto.

npm ci --ignore-scripts
npm run typecheck
npm test
npm run build
npm run test:dist
npm --ignore-scripts run validate

Estas verificaciones usan fixtures locales, simulaciones y pruebas de protocolo. No se requiere ninguna solicitud de imagen de pago. No se ha realizado ni se afirma ninguna verificación en vivo del proveedor.

Licencia

MIT © 2026 KPK. Consulta LICENSE y THIRD_PARTY_NOTICES.md.