gimp-mcp

MCP-сервер, который управляет GIMP 3 для скриптового редактирования изображений: кадрирование, изменение размера, подгонка под соотношение сторон, лёгкая цветокоррекция, проверка соответствия спецификациям размеров и пакетная обработка папки.

Собран и проверен на Windows с GIMP 3.2.4, с использованием GObject Introspection Python API GIMP 3 (gi.repository.Gimp) вместо старого интерфейса Script-Fu 2.x.

Для чего это нужно

Любой рабочий процесс, где к изображениям нужно многократно применять одно и то же детерминированное преобразование, и вы предпочли бы описать его, а не кликать по нему:

• обрезать фото под целевое соотношение сторон или под наибольший центрированный квадрат

• изменить размер папки изображений так, чтобы длинная сторона была не больше 2000px

• проверить, соответствуют ли изображения требованию по размеру/ориентации перед публикацией

• применить один конвейер кадрирования и изменения размера ко всей съёмке за один проход

Related MCP server: gimp-mcp

Что вас подведёт: EXIF-ориентация

Фотографии с телефонов и многих камер часто хранятся в альбомной ориентации с тегом EXIF-ориентации, который указывает просмотрщикам повернуть их. Фото, которое все видят как портрет 3000x4000, может храниться как 4000x3000.

Неинтерактивный загрузчик GIMP не применяет этот тег. Наивное «кадрирование по квадрату по центру» поэтому обрезает не ту ось и даёт перевёрнутое изображение — при этом сообщая правдоподобные размеры, так что ничего не выглядит явно сломанным, пока вы не откроете результат.

Каждая загрузка в этом проекте проходит через load_image(), которая сначала вызывает Gimp.Image.policy_rotate(), так что вся геометрия — и каждый размер, о котором сообщает этот сервер — указана в отображаемой ориентации, то есть так, как зритель на самом деле видит изображение. Это покрыто тестом.

Архитектура

Два исполнительных бэкенда, одна общая среда выполнения операций:

                    ┌───────────────────────────────┐
  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 записывает указатель runtime_path.txt рядом с установленным плагином, а не копирует gimp_runtime.py, так что на диске существует ровно одна копия кода операций.

Выбор бэкенда. headless — значение по умолчанию, и именно его используют все пакетные и детерминированные операции — он не требует открытого GIMP и является надёжным путём. bridge предназначен для живой работы над документом, который у вас уже открыт. Оба проверены на пиксельно идентичный вывод.

Почему TCP, а не D-Bus

Существующие проекты живого управления GIMP используют D-Bus, которого нет в Windows. Loopback-TCP-сокет достигает того же и является кроссплатформенным. Он привязывается только к 127.0.0.1 и никогда не открывается в сеть.

Установка

Требуется GIMP 3.x (разрабатывалось под 3.2.4) и Python-пакет mcp.

Примечание о зависимости mcp. Это нацелено на SDK 1.x пакета mcp и закреплено за mcp>=1.0,<2. Версия 2.0 удалила mcp.server.fastmcp и переименовала FastMCP в MCPServer; портирование на неё ещё не сделано, а незакреплённая установка подхватит 2.x и упадёт при импорте.

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

Мост-плагин нужен только для инструментов живого управления. Пакетные инструменты и инструменты для одиночных изображений работают без установки чего-либо в GIMP.

Расположение плагина

install_plugin.py обнаруживает те каталоги конфигурации GIMP 3.x, которые реально существуют, а не хардкодит версию. На Windows это:

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

Обратите внимание: это версионированный каталог (3.2 для GIMP 3.2, а не 3.0), и GIMP 3 требует, чтобы каждый плагин лежал в папке, имя которой совпадает с именем .py-файла. На Linux и macOS установщик ищет в ~/.config/GIMP/3.x/ и ~/Library/Application Support/GIMP/3.x/ соответственно.

Регистрация MCP-сервера

Установка пакета предоставляет консольный скрипт gimp-mcp, который удобнее всего регистрировать, потому что он не зависит от рабочего каталога:

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": []
    }
  }
}

В Claude Code эквивалентная однострочная команда:

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

Запуск модуля напрямую тоже работает, если mcp импортируем в этом интерпретаторе:

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

Необязательные переменные окружения:

Инструменты

Проверка

Одиночное изображение

Пакетная обработка

Весь пакет выполняется в рамках одного вызова GIMP. Консоль GIMP запускается несколько секунд, поэтому запуск на каждый файл был бы медленным — измерено ~в 2.4 раза дешевле на файл для небольшой папки, и выигрыш растёт с размером папки. Файл, который не прошёл, не прерывает выполнение; он попадает в errors, а остальные продолжают работу.

Живое управление (требуется мост-плагин)

Запустите мост в GIMP: Фильтры > Разработка > Start MCP Bridge.

Спецификации изображений

check_image_spec, fit_to_spec и их пакетные эквиваленты используют одну модель спецификации. Каждое ограничение необязательно — 0 означает отсутствие ограничения, а ориентация any означает отсутствие требования по ориентации.

fit_to_spec удовлетворяет спецификацию тремя упорядоченными шагами: кадрирование для исправления ориентации, увеличение до минимума, уменьшение до максимума. Уже выполненные ограничения не трогают кадрирование.

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

Цветокоррекция намеренно ограничена

adjust_image ограничивает яркость/контраст диапазоном -0.5..0.5 и отклоняет всё, что за его пределами, а не обрезает. Значения за пределами примерно ±0.15 заметно меняют характер фотографии, что важно, когда изображение должно достоверно представлять реальный объект. Намеренно нет усиления насыщенности или «автоулучшения».

Проверка

Запустите набор тестов:

python -m pytest tests/ -v

Тесты, которым нужны реальные изображения, пропускаются, если не указать их:

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 должен быть независимо созданным центрированным квадратным кадром из GIMP_MCP_TEST_IMAGE — например, обрезанным вручную в GIMP. Главный тест утверждает, что crop_square воспроизводит этот эталон, а не просто выполняется без ошибок.

На эталонной фотографии, использовавшейся при разработке (JPEG 4000x3000 с EXIF-ориентацией 6, отображающийся как 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%

Этот остаток — шум перекодирования JPEG — одно только перекодирование даёт ~0.5 среднего — а не разница в геометрии, и оба бэкенда полностью совпадают.

Набор также покрывает: сообщение об отображаемой ориентации, спецификации ориентации и минимального размера, отклонение кадров за границами, отклонение корректировок вне диапазона, движение яркости в правильную сторону, цепочки конвейеров, кадрирование по соотношению сторон, пакетную обработку папки, аудит только для чтения, понятные ошибки для отсутствующих файлов и полный проход по реальному протоколу MCP stdio.

Устранение неполадок

gimp-console not found — задайте GIMP_CONSOLE полным путём к gimp-console-3.exe.

Инструменты моста падают с «Could not reach the GIMP bridge» — GIMP не открыт или мост не запущен. Выполните Фильтры > Разработка > Start MCP Bridge. gimp_status показывает оба бэкенда одновременно.

Пункт меню отсутствует после установки — перезапустите GIMP; он сканирует плагины только при запуске. Убедитесь, что структура — plug-ins/gimp-mcp-bridge/gimp-mcp-bridge.py (имя папки должно совпадать с именем файла).

Диагностика плагина — плагин GIMP — это отдельный процесс, чей stderr невидим, когда GIMP работает как GUI-приложение в Windows. Мост пишет в bridge.log рядом с установленным плагином.

Диалог цветового профиля блокирует GIMP при запуске при открытии изображения со встроенным профилем в режиме GUI. В headless-режиме он не появляется, что является ещё одной причиной, почему пакетная работа использует headless-бэкенд.

Пакетная обработка завершилась по таймауту — по умолчанию 600 секунд на весь запуск; для очень больших папок может потребоваться больше.

Известные ограничения

• Живое управление проверено лишь поверхностно. Оно проверено в работе (открытие изображения, список, скриншот, живое редактирование и кадрирование через bridge с результатом, идентичным headless-режиму), но использовалось гораздо реже, чем headless-путь. Считайте headless-режим надёжным.

• Bridge по замыслу выполняет произвольный код Python. Он работает только через loopback и запускается вручную, а не автоматически, но всё, что может обратиться к localhost на машине, может управлять GIMP, пока он запущен. Останавливайте его, когда он не используется.

• Запуск bridge блокирует его собственный процесс plug-in — именно это поддерживает его в рабочем состоянии. Он не замораживает интерфейс GIMP, но GIMP показывает plug-in как запущенный.

• Сам пункт меню GUI не покрыт автоматизированными тестами. Процедура, которую он вызывает, проверена; путь кликов — нет.

• Проверена только Windows. Пути кода кроссплатформенные, и установщик обрабатывает каталоги конфигурации Linux/macOS, но ни то, ни другое не тестировалось.

• SDK mcp 2.x пока не поддерживается -- см. примечание в разделе Install.

• Никакого удаления фона или переноса стиля с помощью ИИ. Некоторые аналогичные проекты заявляют об этом без работающей реализации за этими заявлениями; здесь это намеренно не заявляется.

Примечания о существующих решениях

Разделение между plug-in на стороне GIMP, предоставляющим bridge, и отдельным процессом MCP-сервера, который подключается к нему как клиент, — естественная форма для этой задачи, и она используется в других проектах GIMP MCP. Пакетная обработка и конвейеры в стиле пресетов распространены в нескольких из них. Управление живым холстом существует в других местах через D-Bus, здесь оно заменено на loopback TCP для поддержки Windows. Никакой код не был скопирован ни из одного из них; особенности Windows — реальный путь plug-in, время жизни процесса plug-in, сигнатура run-callback и поведение EXIF — были установлены непосредственно на основе GIMP 3.2.4.

Лицензия

MIT — см. LICENSE.