gimp-mcp

Un servidor MCP que controla GIMP 3 para edición de imágenes mediante scripts: recorte, redimensionado, ajuste de proporción, retoque de color ligero, validación de especificaciones de dimensiones y procesamiento por lotes en una carpeta.

Construido y verificado en Windows con GIMP 3.2.4, usando la API de Python de GObject Introspection de GIMP 3 (gi.repository.Gimp) en lugar de la antigua interfaz Script-Fu 2.x.

Para qué sirve

Cualquier flujo de trabajo donde las imágenes necesiten el mismo tratamiento determinista aplicado repetidamente y prefieras describirlo en lugar de hacer clic:

• recortar una foto a una proporción objetivo, o al cuadrado centrado más grande

• redimensionar una carpeta de imágenes para que el borde más largo tenga como máximo 2000px

• comprobar si las imágenes cumplen un requisito de tamaño/orientación antes de publicarlas

• aplicar un mismo pipeline de recorte y redimensionado a toda una sesión en una sola pasada

Related MCP server: gimp-mcp

Lo único que te va a morder: la orientación EXIF

Las fotos de teléfonos y muchas cámaras se almacenan frecuentemente en horizontal con una etiqueta de orientación EXIF que indica a los visores que las roten. Una foto que todos ven como retrato de 3000x4000 puede estar almacenada como 4000x3000.

El cargador no interactivo de GIMP no aplica esa etiqueta. Un recorte "a cuadrado, centrado" ingenuo corta por tanto el eje equivocado y produce una imagen girada — mientras sigue reportando dimensiones que parecen plausibles, así que nada parece roto hasta que abres el resultado.

Cada carga en este proyecto pasa por load_image(), que llama primero a Gimp.Image.policy_rotate(), de modo que toda la geometría — y cada dimensión que este servidor reporta — está en orientación mostrada, es decir, lo que un visor realmente ve. Esto está cubierto por una prueba.

Arquitectura

Dos backends de ejecución, un runtime de operaciones compartido:

                    ┌───────────────────────────────┐
  MCP client ──────►│  gimp_mcp/server.py (stdio)   │
                    └───────────┬───────────────────┘
                                │
              ┌─────────────────┴──────────────────┐
              ▼                                    ▼
   HeadlessBackend                        BridgeBackend
   spawns gimp-console-3.exe              TCP 127.0.0.1:50472
   (no running GIMP needed)               (into a running GIMP)
              │                                    │
              ▼                                    ▼
      bootstrap.py                    plug-ins/gimp-mcp-bridge/
              │                                    │
              └──────────────┬─────────────────────┘
                             ▼
              gimp_mcp/gimp_runtime.py
              THE single source of truth for every
              image operation. Both paths share it,
              so batch and live cannot drift apart.

install_plugin.py escribe un puntero runtime_path.txt junto al plug-in instalado en lugar de copiar gimp_runtime.py, de modo que existe exactamente una copia del código de operaciones en disco.

Elección de backend. headless es el predeterminado y es el que se usa para todo el trabajo por lotes y determinista — no necesita un GIMP abierto y es la vía fiable. bridge es para trabajo en vivo sobre un documento que ya tienes abierto. Ambos están verificados para producir salida de píxeles idéntica.

Por qué TCP y no D-Bus

Los proyectos existentes de control de GIMP en vivo usan D-Bus, que no existe en Windows. Un socket TCP de bucle local logra lo mismo y es multiplataforma. Se enlaza solo a 127.0.0.1 y nunca se expone a la red.

Instalación

Requiere GIMP 3.x (desarrollado contra 3.2.4) y el paquete de Python mcp.

Nota sobre la dependencia mcp. Esto apunta al SDK de mcp 1.x y está fijado a mcp>=1.0,<2. La versión 2.0 eliminó mcp.server.fastmcp y renombró FastMCP a MCPServer; la migración a ella aún no está hecha, y una instalación sin fijar recoge 2.x y falla en la importación.

pip install -r requirements.txt
python install_plugin.py          # install the bridge plug-in (optional)
python install_plugin.py --list   # show detected GIMP config dirs

El plug-in de puente solo se necesita para las herramientas de control en vivo. Las herramientas de lote y de imagen única funcionan sin instalar nada en GIMP.

Ubicación del plug-in

install_plugin.py descubre los directorios de configuración de GIMP 3.x que realmente existen en lugar de fijar una versión. En Windows es:

%APPDATA%\GIMP\3.2\plug-ins\gimp-mcp-bridge\gimp-mcp-bridge.py

Nótese que es el directorio versionado (3.2 para GIMP 3.2, no 3.0), y GIMP 3 requiere que cada plug-in esté en una carpeta cuyo nombre coincida con el archivo .py. En Linux y macOS el instalador busca en ~/.config/GIMP/3.x/ y ~/Library/Application Support/GIMP/3.x/ respectivamente.

Registrar el servidor MCP

Instalar el paquete proporciona un script de consola gimp-mcp, que es la forma más limpia de registrarlo porque no depende de un directorio de trabajo:

python -m venv .venv
.venv/Scripts/python -m pip install -e .     # .venv/bin/python on Unix

{
  "mcpServers": {
    "gimp": {
      "type": "stdio",
      "command": "/path/to/gimp-mcp/.venv/Scripts/gimp-mcp.exe",
      "args": []
    }
  }
}

Con Claude Code, el equivalente en una línea es:

claude mcp add gimp --scope user -- /path/to/gimp-mcp/.venv/Scripts/gimp-mcp.exe

Ejecutar el módulo directamente también funciona, si mcp es importable en ese intérprete:

{
  "mcpServers": {
    "gimp": {
      "command": "python",
      "args": ["-m", "gimp_mcp"],
      "cwd": "/path/to/gimp-mcp"
    }
  }
}

Variables de entorno opcionales:

Herramientas

Inspección

Imagen única

Lote

Un lote completo se ejecuta dentro de una invocación de GIMP. La consola de GIMP tarda varios segundos en arrancar, así que generar un proceso por archivo sería lento — medido en ~2.4x más barato por archivo para una carpeta pequeña, y el ahorro crece con el tamaño de la carpeta. Un archivo que falla no aborta la ejecución; cae en errors y el resto continúa.

Control en vivo (necesita el plug-in de puente)

Inicia el puente en GIMP: Filtros > Desarrollo > Iniciar puente MCP.

Especificaciones de imagen

check_image_spec, fit_to_spec y sus equivalentes por lotes comparten un mismo modelo de especificación. Cada restricción es opcional — 0 significa sin límite, y orientación any significa sin requisito de orientación.

fit_to_spec satisface una especificación en tres pasos ordenados: recortar para corregir la orientación, ampliar para alcanzar el mínimo, reducir para respetar el máximo. Las restricciones ya satisfechas dejan el encuadre intacto.

// A square image at least 1000x1000, capped at 2000x2000
{ "orientation": "square", "min_width": 1000, "min_height": 1000,
  "max_width": 2000, "max_height": 2000 }

El ajuste de color está deliberadamente limitado

adjust_image restringe el brillo/contraste a -0.5..0.5 y rechaza cualquier valor fuera de ese rango en lugar de recortarlo. Valores más allá de aproximadamente ±0.15 cambian visiblemente el carácter de una foto, lo que importa cuando una imagen necesita representar fielmente un sujeto real. No hay intencionadamente ningún aumento de saturación ni "mejora automática".

Verificación

Ejecuta la suite:

python -m pytest tests/ -v

Las pruebas que necesitan imágenes reales se omiten a menos que les apuntes a algunas:

export GIMP_MCP_TEST_IMAGE=/path/to/photo.jpg          # ideally EXIF-rotated
export GIMP_MCP_TEST_REFERENCE=/path/to/photo-square.jpg

GIMP_MCP_TEST_REFERENCE debe ser un recorte cuadrado centrado producido independientemente de GIMP_MCP_TEST_IMAGE — recortado a mano en GIMP, por ejemplo. La prueba principal afirma que crop_square reproduce esa referencia, en lugar de simplemente ejecutarse sin error.

En la foto de referencia usada durante el desarrollo (un JPEG de 4000x3000 con orientación EXIF 6, mostrado como 3000x4000):

crop_square vs hand-made reference : mean abs diff 0.236, max 18, outliers 0.0014%
same crop via the bridge backend   : mean abs diff 0.236, max 18, outliers 0.0014%

Ese residual es ruido de re-codificación JPEG — re-codificar solo da ~0.5 de media — no una diferencia de geometría, y ambos backends coinciden exactamente.

La suite también cubre el reporte de orientación mostrada, especificaciones de orientación y tamaño mínimo, recortes fuera de límites rechazados, ajustes fuera de rango rechazados, brillo moviendo píxeles en la dirección correcta, pipelines encadenados, recorte por proporción, lote sobre una carpeta, la auditoría de solo lectura, errores claros para archivos faltantes, y una pasada completa sobre el protocolo real de stdio de MCP.

Solución de problemas

gimp-console not found — establece GIMP_CONSOLE a la ruta completa de gimp-console-3.exe.

Las herramientas de puente fallan con "Could not reach the GIMP bridge" — GIMP no está abierto, o el puente no se inició. Ejecuta Filtros > Desarrollo > Iniciar puente MCP. gimp_status muestra ambos backends a la vez.

El elemento de menú falta después de instalar — reinicia GIMP; solo escanea plug-ins al inicio. Confirma que la estructura es plug-ins/gimp-mcp-bridge/gimp-mcp-bridge.py (el nombre de la carpeta debe coincidir con el nombre del archivo).

Diagnosticar el plug-in — un plug-in de GIMP es un proceso separado cuyo stderr es invisible cuando GIMP se ejecuta como aplicación GUI en Windows. El puente escribe en bridge.log junto al plug-in instalado.

Un diálogo de perfil de color bloquea GIMP al inicio al abrir una imagen con un perfil incrustado en modo GUI. No aparece en modo headless, que es otra razón por la que el trabajo por lotes usa el backend headless.

Lote agotó el tiempo — el predeterminado es 600s para toda la ejecución; carpetas muy grandes pueden necesitar más.

Limitaciones conocidas

• El control en vivo solo se ha ejercitado ligeramente. Está verificado que funciona (abrir una imagen, listar, capturar pantalla, editar en vivo y recortar a través del bridge con una salida idéntica a la del modo headless), pero ha tenido mucho menos uso que la ruta headless. Trata el modo headless como el fiable.

• El bridge ejecuta Python arbitrario por diseño. Es solo de loopback y se inicia manualmente en lugar de automáticamente, pero cualquier cosa que pueda alcanzar localhost en la máquina puede controlar GIMP mientras esté en ejecución. Detenlo cuando no esté en uso.

• El inicio del bridge bloquea su propio proceso de plug-in — eso es lo que lo mantiene vivo. No congela la interfaz de GIMP, pero GIMP muestra el plug-in como en ejecución.

• El elemento de menú de la GUI en sí no está cubierto por pruebas automatizadas. El procedimiento que invoca está verificado; la ruta de clic no lo está.

• Solo Windows está verificado. Las rutas de código son multiplataforma y el instalador maneja los directorios de configuración de Linux/macOS, pero ninguno ha sido probado.

• El SDK de mcp 2.x aún no es compatible -- consulta la nota en Instalación.

• Sin eliminación de fondo ni transferencia de estilo con IA. Algunos proyectos comparables promocionan estas funciones sin una implementación funcional detrás; aquí no se reivindican deliberadamente.

Notas sobre trabajos previos

La división entre un plug-in del lado de GIMP que expone un bridge y un proceso de servidor MCP independiente que se conecta a él como cliente es una forma natural para este problema y es utilizada por otros proyectos MCP de GIMP. El procesamiento por lotes y los pipelines de estilo preestablecido son comunes en varios. El control de lienzo en vivo existe en otros lugares mediante D-Bus, reemplazado aquí con TCP de loopback para soporte de Windows. No se copió código de ninguno de ellos; las particularidades de Windows — la ruta real del plug-in, la vida útil del proceso del plug-in, la firma de run-callback y el comportamiento de EXIF — se establecieron directamente contra GIMP 3.2.4.

Licencia

MIT — consulta LICENSE.