imgx-mcp

Servidor MCP de generación y edición de imágenes con IA. Conversión de texto a imagen, edición basada en texto con refinamiento iterativo. Múltiples proveedores (Gemini + OpenAI).

GitHubPrueba este MCPPatrocinado

Documentación

imgx-mcp

Servidor MCP de generación y edición de imágenes con IA. Funciona con Claude Code, Gemini CLI, Cursor, Windsurf y cualquier herramienta compatible con MCP.

Genera imágenes a partir de texto, edita imágenes existentes con instrucciones de texto, itera sobre los resultados — todo desde tu entorno de codificación con IA.

Qué hace diferente a imgx-mcp

Sin ingeniería de prompts — Tu agente de IA mantiene el contexto de la conversación y construye automáticamente prompts optimizados. Di lo que necesitas; el agente maneja la estructura del prompt, la selección del modelo y las dimensiones específicas de cada plataforma
24 técnicas de edición integradas — Atmósfera, composición, transferencia de estilo, manipulación de elementos y estilos de tendencia — empaquetadas como una Skill que tu agente aplica bajo demanda
Gestión de sesiones con deshacer/rehacer — Edita de forma iterativa, retrocede a cualquier punto, crea ramas o cambia entre sesiones paralelas — control de versiones para imágenes

Inicio rápido

Añádelo a la configuración MCP de tu herramienta (.mcp.json, settings.json, etc.):

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": { "GEMINI_API_KEY": "your-key" }
    }
  }
}

Eso es todo. Tu agente de IA ya puede generar y editar imágenes.

Windows: Reemplaza "command": "npx" por "command": "cmd" y antepone "/c" al arreglo de args.

Skill (Claude Code)

Para usuarios de Claude Code, imgx-mcp incluye una skill image-generation — un prompt guiado que enseña a Claude a usar las herramientas MCP de forma eficaz. Con la skill instalada, escribe /image-generation para iniciar un flujo de trabajo guiado.

Instalar la skill

Copia el directorio de la skill desde el paquete npm o el repositorio de GitHub a tu proyecto:

# From npm (after npx has cached the package)
cp -r $(npm root -g)/imgx-mcp/skills .claude/skills

# Or from the GitHub repository
curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/SKILL.md \
  -o .claude/skills/image-generation/SKILL.md --create-dirs
curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/references/providers.md \
  -o .claude/skills/image-generation/references/providers.md --create-dirs

O coloca los archivos de la skill manualmente:

your-project/
  .mcp.json                              ← MCP server config (Quick start above)
  .claude/
    skills/
      image-generation/
        SKILL.md                         ← skill prompt
        references/
          providers.md                   ← provider reference

Los archivos de la skill están incluidos en el paquete npm bajo skills/ y en el repositorio de GitHub.

Skill personal (todos los proyectos): Colócala en ~/.claude/skills/image-generation/ en lugar de .claude/skills/.

Claude Desktop

Claude Desktop admite skills mediante carga ZIP:

Descarga image-generation-skill.zip del repositorio (o encuéntralo en el paquete npm bajo dist/)
En Claude Desktop: Settings > Profile > Customize > Skills > Add Skill
Sube el ZIP

Actualiza la skill volviendo a descargar y volviendo a subir el ZIP después de nuevos lanzamientos.

Qué aporta la Skill

El servidor MCP le da a la IA la capacidad de generar y editar imágenes. La Skill añade el conocimiento de cómo usar esas herramientas correctamente — para que no necesites aprender sintaxis de prompts, especificaciones de modelos ni parámetros específicos del servicio.

Construcción automática de prompts — Di "Necesito una imagen de portada". La IA construye un prompt estructurado usando el marco Sujeto-Contexto-Estilo: qué mostrar, dónde colocarlo, cómo debe verse
24 técnicas de edición — Ajuste de atmósfera, cambios de composición, manipulación de elementos, transferencia de estilo. "Hazlo más cálido" o "añade profundidad de campo" — la IA selecciona la instrucción correcta para el modelo
Selección inteligente de modelo — Comienza con el modelo gratuito. Sugiere actualizaciones de pago solo cuando tus necesidades superan las capacidades del nivel gratuito, y explica qué cambios implica
Dimensionado consciente de la plataforma — "OGP de Twitter" o "captura de App Store" — la IA elige la relación de aspecto y resolución correctas. Cubre redes sociales, OGP, tiendas de aplicaciones, impresión y plataformas de blogs
Plantillas de estilos de tendencia — Ghibli, figura de acción en caja, arcilla 3D, pixel art, chibi y más. Nombra el estilo y la IA aplica la estructura de prompt correcta
Consistencia multi-imagen — Los tokens de diseño y las plantillas de ADN de personajes mantienen la coherencia visual en presentaciones de diapositivas, series de redes sociales y activos de marca

Los modelos de generación de imágenes ya tienen estas capacidades. La Skill es lo que las hace accesibles sin conocimiento especializado.

Servidor MCP vs Skill

	Servidor MCP	Skill
Qué hace	Expone herramientas de imagen a los agentes de IA	Prompt guiado para usar las herramientas
Funciona con	Cualquier herramienta compatible con MCP	Claude Code, Claude Desktop
Instalación	Añadir a `.mcp.json`	Copiar archivos de la skill al proyecto
Compartir en equipo	Confirmar `.mcp.json` en el repositorio	Confirmar `.claude/skills/` en el repositorio

Recomendado: Configura el servidor MCP (Inicio rápido) + instala la skill si usas Claude Code.

Herramientas MCP

Herramienta	Descripción
`generate_image`	Genera una imagen a partir de un prompt de texto
`edit_image`	Edita una imagen existente con instrucciones de texto
`edit_last`	Edita la última imagen generada/editada (no se necesita ruta de entrada)
`undo_edit`	Deshace la última edición, volviendo a la imagen anterior en la sesión
`redo_edit`	Rehace una edición previamente deshecha
`edit_history`	Muestra todas las sesiones y su historial de ediciones con metadatos
`switch_session`	Cambia a una sesión de edición diferente
`clear_history`	Limpia el historial del proyecto (opcionalmente elimina los archivos de imagen)
`set_output_dir`	Cambia el directorio de salida predeterminado (opcionalmente mueve archivos existentes)
`list_providers`	Lista los proveedores y capacidades disponibles

El directorio .imgx/ almacena tanto el historial de ediciones como la salida de imágenes predeterminada. Su ubicación depende de la detección de la raíz del proyecto:

Raíz del proyecto	Ubicación de `.imgx/`	Historial
Detectada	`<project-root>/.imgx/`	`<project-root>/.imgx/output-history.json`
No detectada	`~/Pictures/imgx/` (solo imágenes)	`~/.config/imgx/output-history.json` (global)

Todos los clientes que resuelven a la misma raíz de proyecto comparten el mismo historial. Cada sesión tiene su propio subdirectorio. Las rutas de archivo se devuelven en la respuesta. La vista previa de la imagen en línea se incluye en las respuestas MCP (base64).

Edición iterativa

La herramienta edit_last usa la salida de la llamada anterior a generate_image o edit_image como entrada. Esto permite un flujo de trabajo conversacional:

"Generate a coffee shop interior" → generate_image
"Make the lighting warmer"        → edit_last
"Add a person reading a book"     → edit_last

No es necesario especificar rutas de archivo entre pasos.

Gestión de sesiones

Cada llamada a generate_image inicia una nueva sesión. Las llamadas posteriores a edit_last se añaden a la misma sesión, formando una cadena de ediciones. Cada sesión tiene su propio directorio de salida.

Deshacer / Rehacer — Retrocede y avanza por la cadena de ediciones:

generate → edit_last → edit_last → edit_last
                                    ↑ current
                       ← undo_edit
                       ↑ current
                            redo_edit →
                                    ↑ current

Después de deshacer, llamar a edit_last crea una rama desde la posición actual (las entradas abandonadas y sus archivos se eliminan del disco).

Nombrado de archivos — edit_last genera nombres de archivo secuenciales basados en el archivo de origen:

generate_image             → cover.png
edit_last                  → cover-1.png
edit_last                  → cover-2.png

generate_image (no output) → imgx-a1b2c3d4.png
edit_last                  → imgx-a1b2c3d4-1.png

Cambio de sesión — Usa edit_history para ver todas las sesiones y luego switch_session para reanudar una sesión anterior. La herramienta edit_last usará la posición actual en la sesión cambiada.

Directorio de salida — edit_last hereda el directorio de salida de la sesión. Si se llamó a generate_image con output_dir, todas las llamadas posteriores a edit_last en esa sesión producen salida en el mismo directorio. La ruta output_dir se registra como metadato de sesión en output-history.json. Esto solo afecta a dónde se guardan los archivos de imagen — el historial siempre permanece en .imgx/ (o en el directorio de configuración global).

Configuración de clave de API

Configura al menos un proveedor:

Gemini — obtén una clave de Google AI Studio (nivel gratuito disponible para gemini-2.5-flash-image):

imgx config set api-key YOUR_GEMINI_API_KEY --provider gemini

OpenAI — obtén una clave de OpenAI Platform:

imgx config set api-key YOUR_OPENAI_API_KEY --provider openai

Las claves se almacenan en ~/.config/imgx/config.json (Linux/macOS) o %APPDATA%\imgx\config.json (Windows). Alternativamente, pasa las claves a través de la sección env en tu configuración MCP, o define variables de entorno:

export GEMINI_API_KEY="your-api-key"
export OPENAI_API_KEY="your-api-key"

Incluye solo las claves de API de los proveedores que quieras usar. Se requiere al menos una.

Configuración MCP por herramienta

Claude Code

.mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": { "GEMINI_API_KEY": "your-key", "OPENAI_API_KEY": "your-key" }
    }
  }
}

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": { "GEMINI_API_KEY": "your-key", "OPENAI_API_KEY": "your-key" }
    }
  }
}

Claude Desktop

claude_desktop_config.json:

macOS / Linux:

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "OPENAI_API_KEY": "your-key",
        "IMGX_PROJECT_ROOT": ""
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "imgx": {
      "command": "cmd",
      "args": ["/c", "npx", "--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "OPENAI_API_KEY": "your-key",
        "IMGX_PROJECT_ROOT": ""
      }
    }
  }
}

IMGX_PROJECT_ROOT — Configúralo con la ruta de tu proyecto para guardar imágenes dentro del proyecto (p. ej. "C:\\Users\\you\\my-project"). Déjalo vacío para usar el valor global predeterminado (~/Pictures/imgx).

Ubicación del archivo de configuración: %APPDATA%\Claude\claude_desktop_config.json (Windows) o ~/Library/Application Support/Claude/claude_desktop_config.json (macOS). Después de editarlo, reinicia Claude Desktop.

Nota: Claude Desktop no admite la detección automática (raíces MCP / búsqueda de .imgxrc basada en CWD). Usa IMGX_PROJECT_ROOT en la configuración anterior (por cliente), o ejecuta imgx config set project-root /path/to/project (compartido entre todos los clientes).

Codex CLI

.codex/config.toml:

[mcp_servers.imgx]
command = "npx"
args = ["--package=imgx-mcp", "-y", "imgx-mcp"]
env = { GEMINI_API_KEY = "your-key", OPENAI_API_KEY = "your-key" }

Otras herramientas

El mismo patrón npx funciona con Cursor, Windsurf, Continue.dev, Cline, Zed y otras herramientas compatibles con MCP. En Windows, usa cmd /c npx en lugar de npx directamente.

Proveedores

Proveedor	Modelos	Capacidades
Gemini	`gemini-2.5-flash-image` (Nano Banana — nivel gratuito, predeterminado), `gemini-3-pro-image-preview` (Nano Banana Pro), `gemini-3.1-flash-image-preview` (Nano Banana 2)	Generar, editar, relación de aspecto (hasta 14 proporciones), resolución (hasta 4K), imágenes de referencia, control de personas
OpenAI	`gpt-image-1`, `gpt-image-1.5` (más rápido, 20 % más barato), `gpt-image-1-mini` (económico)	Generar, editar, relación de aspecto, salida múltiple, formato de salida (PNG/JPEG/WebP), transparencia de fondo

Arquitectura

imgx separa las preocupaciones independientes del modelo y dependientes del modelo:

MCP server (tool definitions, stdio transport)    CLI (argument parsing, output formatting)
 ↓                                                 ↓
Core (Capability enum, ImageProvider interface, provider registry, file I/O, history)
 ↓
Provider (model-specific API calls, capability declarations)

El servidor MCP y la CLI son dos puntos de entrada al mismo núcleo. Ambos llaman a las mismas funciones de proveedor.

Cada proveedor declara sus capacidades compatibles. Añadir un nuevo proveedor significa implementar la interfaz ImageProvider y registrarla — sin cambios en la capa MCP o CLI.

Sistema de capacidades

Capacidad	Descripción
`TEXT_TO_IMAGE`	Generar imágenes a partir de prompts de texto
`IMAGE_EDITING`	Editar imágenes con instrucciones de texto
`ASPECT_RATIO`	Controlar la relación de aspecto de salida
`RESOLUTION_CONTROL`	Controlar la resolución de salida
`MULTIPLE_OUTPUTS`	Generar múltiples imágenes por solicitud
`REFERENCE_IMAGES`	Usar imágenes de referencia como guía
`PERSON_CONTROL`	Controlar la generación de personas en la salida
`OUTPUT_FORMAT`	Elegir formato de salida (PNG, JPEG, WebP)

CLI

imgx-mcp también funciona como herramienta independiente de línea de comandos.

Instalación

npm install -g imgx-mcp

Requiere Node.js 18+.

Uso

# Generate
imgx generate -p "A coffee cup on a wooden table, morning light" -o output.png

# Edit
imgx edit -i photo.png -p "Change the background to sunset" -o edited.png

# Iterative editing
imgx edit -i photo.png -p "Make the background darker"
imgx edit --last -p "Add warm lighting"
imgx edit --last -p "Crop to 16:9" -o final.png

# Undo / redo
imgx undo               # Revert to previous image in session
imgx redo               # Re-apply an undone edit

# History
imgx history            # Show all sessions and entries
imgx history switch <session-id>  # Switch to a different session
imgx history clear      # Clear project history (interactive)
imgx history clear --yes          # Clear without confirmation
imgx history clear --keep-files   # Clear history but keep image files
imgx history clear --all          # Clear ALL history across all projects

# Provider management
imgx providers          # List providers and capabilities
imgx capabilities       # Detailed capabilities of current provider

Opciones de CLI

Flag	Corto	Descripción
`--prompt`	`-p`	Descripción de imagen o instrucción de edición (obligatorio)
`--output`	`-o`	Ruta del archivo de salida (auto-generada si se omite)
`--input`	`-i`	Imagen de entrada para editar (solo comando `edit`)
`--last`	`-l`	Usar la última salida como entrada (solo comando `edit`)
`--aspect-ratio`	`-a`	`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` + Gemini 3.x: `1:4`, `1:8`, `4:1`, `4:5`, `5:4`, `8:1`, `21:9`
`--resolution`	`-r`	`1K`, `2K`, `4K`
`--count`	`-n`	Número de imágenes a generar
`--format`	`-f`	Formato de salida: `png`, `jpeg`, `webp` (solo OpenAI)
`--background`	`-b`	Fondo: `transparent`, `opaque`, `auto` (solo OpenAI)
`--quality`	`-q`	Calidad: `low`, `medium`, `high`, `auto` (solo OpenAI)
`--model`	`-m`	Nombre del modelo
`--provider`		Nombre del proveedor (predeterminado: `gemini`)
`--output-dir`	`-d`	Directorio de salida

Configuración

imgx config set api-key <key> --provider gemini   # Save Gemini API key
imgx config set api-key <key> --provider openai   # Save OpenAI API key
imgx config set model <name>      # Set default model
imgx config set output-dir <dir>  # Set default output directory
imgx config set aspect-ratio 16:9 # Set default aspect ratio
imgx config set resolution 2K     # Set default resolution
imgx config list                  # Show all settings
imgx config get api-key           # Show a specific setting (API key is masked)
imgx config path                  # Show config file location

Configuración del proyecto (`.imgxrc`)

Genera una plantilla con imgx init:

imgx init
# → creates .imgxrc in current directory

O créala manualmente:

{
  "defaults": {
    "model": "gemini-2.5-flash-image",
    "outputDir": "./assets/images",
    "aspectRatio": "16:9"
  }
}

La configuración del proyecto se comparte a través de Git. No pongas claves de API en .imgxrc.

Configuración de la raíz del proyecto (3 niveles)

Método	Alcance	Cómo configurar
Variable de entorno `IMGX_PROJECT_ROOT` en la configuración del cliente	Por cliente (mayor prioridad)	Agregar a `env` en `claude_desktop_config.json`, `.mcp.json`, etc.
Detección automática (raíces MCP / búsqueda de `.imgxrc`)	Automático	Funciona en agentes CLI (Claude Code, Gemini CLI). No disponible en Claude Desktop
`imgx config set project-root`	Todos los clientes de la máquina	Almacenado en la configuración del usuario (`~/.config/imgx/config.json` o `%APPDATA%\imgx\config.json`)

Prioridad de detección: variable de entorno → raíces MCP → búsqueda ascendente de .imgxrc → configuración de usuario projectRoot.

El historial se guarda en <project-root>/.imgx/output-history.json (con alcance de proyecto, no compartido con otros proyectos). La salida de imágenes predeterminada va a <project-root>/.imgx/<session-id>/. Las rutas relativas en output y output_dir se resuelven contra la raíz del proyecto en lugar del directorio de trabajo del servidor MCP.

Resolución de configuración

Banderas de CLI (--model, --output-dir, etc.)
Variables de entorno (IMGX_MODEL, IMGX_OUTPUT_DIR, etc.)
Configuración del proyecto (.imgxrc — buscado desde el directorio actual hacia arriba)
Configuración del usuario (~/.config/imgx/config.json o %APPDATA%\imgx\config.json)
Valores predeterminados del proveedor

Formato de salida

Todos los comandos CLI generan JSON:

{"success": true, "filePaths": ["./output.png"]}

Plugin de Claude Code

El plugin combina el servidor MCP + skill en un solo paso. Si prefieres no configurar .mcp.json y los archivos de skill manualmente:

/plugin marketplace add somacoffeekyoto/imgx-mcp
/plugin install imgx-mcp@somacoffeekyoto-imgx-mcp

Actualizar: /plugin → installed → imgx-mcp → update. Si la actualización no muestra cambios, desinstala y reinstala.

Desinstalar: /plugin uninstall imgx-mcp@somacoffeekyoto-imgx-mcp y luego /plugin marketplace remove somacoffeekyoto-imgx-mcp.

Desarrollo

git clone https://github.com/somacoffeekyoto/imgx-mcp.git
cd imgx-mcp
npm install
npm run bundle    # TypeScript compile + esbuild bundle

La compilación produce dos bundles:

dist/mcp.bundle.js — punto de entrada del servidor MCP
dist/cli.bundle.js — punto de entrada de CLI

Desinstalación

Servidor MCP

Elimina la entrada imgx del archivo de configuración MCP de tu herramienta.

Skill

Elimina el directorio image-generation/ de .claude/skills/ o ~/.claude/skills/.

CLI

npm uninstall -g imgx-mcp

npm uninstall elimina el paquete pero no borra la configuración ni los archivos generados. Elimínalos manualmente si es necesario:

Configuración global:

# Linux / macOS
rm -rf ~/.config/imgx/

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:APPDATA\imgx"

Historial e imágenes del proyecto: Cada proyecto puede tener un directorio .imgx/ que contiene el historial de ediciones y las imágenes generadas. Elimínalo de cada proyecto según sea necesario.

rm -rf <project-root>/.imgx/

Licencia

MIT — SOMA COFFEE KYOTO

imgx-mcp

Documentación

imgx-mcp

Qué hace diferente a imgx-mcp

Inicio rápido

Skill (Claude Code)

Instalar la skill

Claude Desktop

Qué aporta la Skill

Servidor MCP vs Skill

Herramientas MCP

Edición iterativa

Gestión de sesiones

Configuración de clave de API

Configuración MCP por herramienta

Claude Code

Gemini CLI

Claude Desktop

Codex CLI

Otras herramientas

Proveedores

Arquitectura

Sistema de capacidades

CLI

Instalación

Uso

Opciones de CLI

Configuración

Configuración del proyecto (.imgxrc)

Configuración de la raíz del proyecto (3 niveles)

Resolución de configuración

Formato de salida

Plugin de Claude Code

Desarrollo

Desinstalación

Servidor MCP

Skill

CLI

Licencia

Enlaces

Configuración del proyecto (`.imgxrc`)