gimp-mcp

Ein MCP-Server, der GIMP 3 für skriptgesteuerte Bildbearbeitung steuert: Zuschneiden, Größenänderung, Seitenverhältnis-Anpassung, leichte Farbkorrekturen, Validierung von Dimensionsspezifikationen und Stapelverarbeitung über einen Ordner.

Erstellt und verifiziert auf Windows mit GIMP 3.2.4, unter Verwendung von GIMP 3s GObject-Introspection-Python-API (gi.repository.Gimp) anstelle der alten 2.x-Script-Fu-Schnittstelle.

Wofür es gedacht ist

Jeder Workflow, bei dem Bilder wiederholt dieselbe deterministische Behandlung benötigen und man sie lieber beschreiben möchte, als durchzuklicken:

• Ein Foto auf ein Ziel-Seitenverhältnis zuschneiden oder auf das größte zentrierte Quadrat

• Einen Ordner mit Bildern so verkleinern, dass die längste Kante höchstens 2000px beträgt

• Prüfen, ob Bilder vor der Veröffentlichung eine Größen-/Orientierungsanforderung erfüllen

• Eine Crop-and-Resize-Pipeline in einem Durchgang auf einen ganzen Shoot anwenden

Related MCP server: gimp-mcp

Die eine Sache, die dich beißen wird: EXIF-Orientierung

Fotos von Handys und vielen Kameras werden häufig im Querformat mit einem EXIF-Orientierungs-Tag gespeichert, das dem Betrachter sagt, sie zu drehen. Ein Foto, das jeder als 3000x4000 Hochformat sieht, kann als 4000x3000 gespeichert sein.

GIMPs nicht-interaktiver Lader wendet dieses Tag nicht an. Ein naives "Zuschneiden auf Quadrat, zentriert" schneidet daher die falsche Achse und erzeugt ein seitenverkehrtes Bild – während es dennoch plausibel aussehende Abmessungen meldet, sodass nichts offensichtlich kaputt aussieht, bis man die Ausgabe öffnet.

Jeder Ladevorgang in diesem Projekt läuft über load_image(), das zuerst Gimp.Image.policy_rotate() aufruft, sodass alle Geometrie – und jede Dimension, die dieser Server meldet – in angezeigter Orientierung ist, d.h. was ein Betrachter tatsächlich sieht. Dies ist durch einen Test abgedeckt.

Architektur

Zwei Ausführungs-Backends, eine gemeinsame Operations-Laufzeit:

                    ┌───────────────────────────────┐
  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 schreibt einen runtime_path.txt-Zeiger neben das installierte Plug-in, anstatt gimp_runtime.py zu kopieren, sodass genau eine Kopie des Operationscodes auf der Festplatte existiert.

Backend-Wahl. headless ist die Standardeinstellung und wird für alle Stapel- und deterministischen Arbeiten verwendet – es benötigt kein geöffnetes GIMP und ist der zuverlässige Pfad. bridge ist für Live-Arbeit an einem Dokument, das bereits geöffnet ist. Beide sind verifiziert, pixelidentische Ausgaben zu erzeugen.

Warum TCP und nicht D-Bus

Bestehende Live-GIMP-Steuerungsprojekte verwenden D-Bus, das es auf Windows nicht gibt. Ein Loopback-TCP-Socket erreicht dasselbe und ist plattformübergreifend. Es bindet nur an 127.0.0.1 und ist niemals dem Netzwerk ausgesetzt.

Installation

Erfordert GIMP 3.x (entwickelt gegen 3.2.4) und das mcp-Python-Paket.

Hinweis zur mcp-Abhängigkeit. Dies zielt auf das mcp 1.x-SDK und ist auf mcp>=1.0,<2 festgelegt. Version 2.0 entfernte mcp.server.fastmcp und benannte FastMCP in MCPServer um; die Portierung darauf ist noch nicht abgeschlossen, und eine nicht festgelegte Installation zieht 2.x und schlägt beim Import fehl.

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

Das Bridge-Plug-in wird nur für die Live-Steuerungs-Werkzeuge benötigt. Die Stapel- und Einzelbild-Werkzeuge funktionieren ohne Installation von etwas in GIMP.

Plug-in-Speicherort

install_plugin.py erkennt, welche GIMP-3.x-Konfigurationsverzeichnisse tatsächlich existieren, anstatt eine Version hart zu codieren. Auf Windows ist das:

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

Beachte, dass es das versionierte Verzeichnis ist (3.2 für GIMP 3.2, nicht 3.0), und GIMP 3 erfordert, dass jedes Plug-in in einem Ordner sitzt, dessen Name mit der .py-Datei übereinstimmt. Auf Linux und macOS sucht der Installer in ~/.config/GIMP/3.x/ bzw. ~/Library/Application Support/GIMP/3.x/.

MCP-Server registrieren

Die Installation des Pakets stellt ein gimp-mcp-Konsolenskript bereit, das die sauberste Möglichkeit zur Registrierung ist, da es nicht von einem Arbeitsverzeichnis abhängt:

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

Mit Claude Code ist das Äquivalent in einer Zeile:

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

Das direkte Ausführen des Moduls funktioniert ebenfalls, wenn mcp in diesem Interpreter importierbar ist:

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

Optionale Umgebungsvariablen:

Werkzeuge

Inspektion

Einzelbild

Stapel

Ein ganzer Stapel läuft innerhalb eines GIMP-Aufrufs. GIMPs Konsole benötigt mehrere Sekunden zum Starten, daher wäre das Spawnen pro Datei langsam – gemessen bei ~2,4x günstiger pro Datei für einen kleinen Ordner, und die Ersparnis wächst mit der Ordnergröße. Eine Datei, die fehlschlägt, bricht den Lauf nicht ab; sie landet in errors und der Rest wird fortgesetzt.

Live-Steuerung (benötigt das Bridge-Plug-in)

Starte die Bridge in GIMP: Filter > Entwicklung > MCP-Bridge starten.

Bildspezifikationen

check_image_spec, fit_to_spec und ihre Stapel-Äquivalente teilen sich ein Spezifikationsmodell. Jede Einschränkung ist optional – 0 bedeutet keine Begrenzung, und Orientierung any bedeutet keine Orientierungsanforderung.

fit_to_spec erfüllt eine Spezifikation in drei geordneten Schritten: Zuschneiden zur Korrektur der Orientierung, Hochskalieren zur Erreichung des Minimums, Herunterskalieren zur Einhaltung des Maximums. Bereits erfüllte Einschränkungen lassen den Bildausschnitt unangetastet.

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

Farbanpassung ist bewusst begrenzt

adjust_image beschränkt Helligkeit/Kontrast auf -0.5..0.5 und lehnt alles außerhalb ab, anstatt zu klemmen. Werte über etwa ±0.15 verändern sichtbar den Charakter eines Fotos, was wichtig ist, wenn ein Bild ein reales Subjekt getreu darstellen soll. Es gibt bewusst keine Sättigungsverstärkung oder "Auto-Verbesserung".

Verifizierung

Führe die Suite aus:

python -m pytest tests/ -v

Tests, die echte Bilder benötigen, werden übersprungen, es sei denn, du weist sie auf einige hin:

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 sollte ein unabhängig erstelltes zentriertes Quadrat-Zuschneiden von GIMP_MCP_TEST_IMAGE sein – zum Beispiel von Hand in GIMP zugeschnitten. Der Haupttest behauptet, dass crop_square diese Referenz reproduziert, anstatt nur ohne Fehler zu laufen.

Auf dem Referenzfoto, das während der Entwicklung verwendet wurde (ein 4000x3000-JPEG mit EXIF-Orientierung 6, das als 3000x4000 angezeigt wird):

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%

Dieser Rest ist JPEG-Neucodierungsrauschen – alleiniges Neucodieren ergibt ~0.5 Mittelwert – nicht ein Geometrieunterschied, und beide Backends stimmen exakt überein.

Die Suite deckt auch die Meldung der angezeigten Orientierung, Orientierungs- und Mindestgrößenspezifikationen, abgelehnte Zuschnitte außerhalb des Bereichs, abgelehnte Anpassungen außerhalb des Bereichs, Helligkeit, die Pixel in die richtige Richtung bewegt, verkettete Pipelines, Seitenverhältnis-Zuschneiden, Stapel über einen Ordner, die schreibgeschützte Prüfung, klare Fehler für fehlende Dateien und einen vollständigen Durchlauf über das echte MCP-stdio-Protokoll ab.

Fehlerbehebung

gimp-console not found – setze GIMP_CONSOLE auf den vollständigen Pfad von gimp-console-3.exe.

Bridge-Werkzeuge schlagen mit "Could not reach the GIMP bridge" fehl – GIMP ist nicht geöffnet, oder die Bridge wurde nicht gestartet. Führe Filter > Entwicklung > MCP-Bridge starten aus. gimp_status zeigt beide Backends gleichzeitig an.

Das Menüelement fehlt nach der Installation – starte GIMP neu; es scannt Plug-ins nur beim Start. Bestätige das Layout als plug-ins/gimp-mcp-bridge/gimp-mcp-bridge.py (der Ordnername muss mit dem Dateinamen übereinstimmen).

Diagnose des Plug-ins – ein GIMP-Plug-in ist ein separater Prozess, dessen stderr unsichtbar ist, wenn GIMP als GUI-App unter Windows läuft. Die Bridge schreibt in bridge.log neben dem installierten Plug-in.

Ein Farbprofil-Dialog blockiert GIMP beim Start, wenn ein Bild mit einem eingebetteten Profil im GUI-Modus geöffnet wird. Er erscheint nicht im Headless-Modus, was ein weiterer Grund ist, warum Stapelarbeiten das Headless-Backend verwenden.

Stapel-Timeout – der Standardwert ist 600s für den gesamten Lauf; sehr große Ordner benötigen möglicherweise mehr.

Bekannte Einschränkungen

• Live-Steuerung ist nur wenig erprobt. Sie ist nachweislich funktionsfähig (Bild öffnen, auflisten, Screenshot, Live-Bearbeitung und Zuschneiden über die Bridge mit identischer Ausgabe wie im Headless-Modus), wurde aber weitaus weniger genutzt als der Headless-Pfad. Behandeln Sie Headless als die vertrauenswürdige Variante.

• Die Bridge führt konstruktionsbedingt beliebigen Python-Code aus. Sie ist nur über Loopback erreichbar und wird manuell statt automatisch gestartet, aber alles, was localhost auf der Maschine erreichen kann, kann GIMP steuern, während sie läuft. Beenden Sie sie, wenn sie nicht verwendet wird.

• Der Bridge-Start blockiert den eigenen Plug-in-Prozess — das hält ihn am Leben. Er friert die GIMP-Oberfläche nicht ein, aber GIMP zeigt das Plug-in als laufend an.

• Der GUI-Menüpunkt selbst ist nicht durch automatisierte Tests abgedeckt. Das Verfahren, das er aufruft, ist verifiziert; der Klickpfad nicht.

• Nur Windows ist verifiziert. Die Codepfade sind plattformübergreifend und der Installer behandelt Linux/macOS-Konfigurationsverzeichnisse, aber keines von beiden wurde getestet.

• Das mcp 2.x SDK wird noch nicht unterstützt -- siehe Hinweis unter Install.

• Keine KI-Hintergrundentfernung oder Stilübertragung. Einige vergleichbare Projekte werben damit, ohne eine funktionierende Implementierung dahinter zu haben; hier wird das bewusst nicht behauptet.

Anmerkungen zu Vorarbeiten

Die Aufteilung zwischen einem GIMP-seitigen Plug-in, das eine Bridge bereitstellt, und einem eigenständigen MCP-Serverprozess, der sich als Client mit ihr verbindet, ist eine natürliche Form für dieses Problem und wird auch von anderen GIMP-MCP-Projekten verwendet. Stapelverarbeitung und Pipelines im Preset-Stil sind bei mehreren üblich. Live-Canvas-Steuerung existiert anderswo über D-Bus und wurde hier durch Loopback-TCP für Windows-Unterstützung ersetzt. Von keinem von ihnen wurde Code kopiert; die Windows-spezifischen Details — der tatsächliche Plug-in-Pfad, die Lebensdauer des Plug-in-Prozesses, die Run-Callback-Signatur und das EXIF-Verhalten — wurden direkt gegen GIMP 3.2.4 ermittelt.

Lizenz

MIT — siehe LICENSE.