GIMP MCP

Produktionsnaher MCP-Server fuer strukturierte GIMP-3-Automation. Ziel ist eine semantische Art-Editing-API fuer KI-Agenten statt GUI-Klickautomation oder tausender roher PDB-Tools.

Getesteter Stand

• GIMP 3.2.2 via offizieller python-fu-eval BatchProcedure

• MCP Python SDK 2.2.x / MCPServer

• XCF-gestuetzte Artwork-Sessions mit Snapshot Undo/Redo

• stabile Layer-IDs ueber GIMP tattoos

• Path Policy gegen Writes ausserhalb freigegebener Roots

• strukturierte Fehlerantworten

• PNG/JPEG/WebP Export und PNG Preview Resource

• PDB Search/Describe

• nicht-destruktive Gimp.DrawableFilter-Effekte

Related MCP server: gimp-local-mcp

Architektur

MCP client -> semantic tools -> SessionManager -> GimpBridge -> GIMP python-fu-eval -> libgimp/PDB/DrawableFilter

Version 0.4 kombiniert crash-isolierte Batch-Aufrufe mit einer optionalen persistenten GIMP-Bridge. Direkte Live-Operationen werden fuer sichere Layer-Mutationen verwendet; bei Ausfall bleibt Batch der deterministische Fallback.

Installation

uv sync
uv run pytest -q
uv run gimp-mcp

Inspector:

uv run mcp dev src/gimp_mcp/server.py:mcp

Streamable HTTP kann mit dem SDK-Runner gestartet werden:

uv run mcp run src/gimp_mcp/server.py:mcp --transport streamable-http

MCP Tools

The public MCP surface is intentionally two-layered: a compact semantic tool set for reliable AI editing, plus expert PDB discovery/calls for installed GIMP features that do not need a dedicated wrapper.

Semantic core:

• Session/document: session_create, session_open, session_info, session_undo, session_redo, session_close, document_save_as, document_resize, document_scale, document_crop, document_flatten.

• Layers/content: layer_create, layer_duplicate, layer_delete, layer_update, layer_fill, layer_reorder, layer_resize, layer_resize_to_image, layer_add_alpha, layer_merge_down, layers_merge_visible, shape_create, text_create, import_layer, transform_layer.

• Selection/layout: selection_set, guide_add, guide_list, guide_delete.

• Effects/output: filter_list, filter_describe, filter_apply, preview_render, vision_capture, export_image, export_artwork, publish_artwork_downloads.

• Runtime/AI: provider, TriForce, live-bridge, headless-workspace and artwork-job lifecycle tools.

Expert coverage:

• pdb_search discovers procedures from the GIMP installation itself.

• pdb_describe returns the exact installed argument/return signature.

• pdb_call provides typed JSON-safe invocation for primitives, the active image, layer/item/channel/path tattoo references, sandboxed GFile, GIMP/GEGL enums, GeglColor, and common named GIMP resources (brush/font/gradient/palette/pattern).

• Specialized GI boxed-array types such as GimpDoubleArray, GimpInt32Array and GimpCoreObjectArray are not claimed as generic JSON-coercible; expose a semantic wrapper for workflows that require them. This avoids a false “complete” claim while preserving safe access to the practical PDB surface.

Preview is additionally exposed as binary MCP resources such as gimp-preview://{session_id}, with vision/timeline resources for agent feedback.

Security

Default erlaubte Roots: ~/Pictures, ~/Downloads, ~/gimp-mcp/workspace, /tmp/gimp-mcp. Ueberschreiben muss explizit aktiviert werden. raw_python wurde aus der normalen Tool-Oberflaeche entfernt.

Konfiguration via Env: GIMP_MCP_GIMP, GIMP_MCP_TIMEOUT, GIMP_MCP_PREVIEW_MAX, GIMP_MCP_ALLOWED_ROOTS, GIMP_MCP_SESSION_ROOT, GIMP_MCP_EXPERT.

Python/GI Fallstrick

GIMPs Python-Plug-ins muessen mit einer Python-Umgebung laufen, die gi/PyGObject besitzt. Eine uv-venv darf /usr/bin/env python3 nicht auf eine inkompatible venv-Python umbiegen. Der Bridge-Prozess entfernt deshalb VIRTUAL_ENV, PYTHONHOME, PYTHONPATH und setzt einen kontrollierten System-PATH.

GIMP 3.2.2 Besonderheit

Gegl.list_operations() laesst den getesteten python-fu-eval Prozess reproduzierbar abstuerzen. 0.1 verwendet deshalb eine kleine validierte Filter-Registry fuer Discovery. Exakte Filter werden weiterhin dynamisch ueber Gimp.DrawableFilter.new() und dessen Config introspektiert. Getestet sind u.a. gegl:gaussian-blur, gegl:brightness-contrast, gegl:unsharp-mask, gegl:color-temperature, gegl:shadows-highlights.

Tests

tests/unit: Path Policy. tests/integration: echte GIMP-Probe, Canvas, Layer, Opacity, XCF und PNG. tests/test_mcp.py: echter MCP Client gegen den Server sowie Tool-Discovery und gimp_status.

Control Center and live observation

GIMP MCP now includes an optional PyQt6 control surface for operating and observing the server:

cd ~/gimp-mcp
./scripts/gimp-mcp-control

The Control Center provides:

• Live — recovered artwork sessions, operation event stream and automatically refreshed previews.

• Server — start/stop the local Streamable HTTP MCP endpoint.

• AI Control — optional art-director provider/model selection through native official-client account integrations.

• Settings — preview interval and size settings stored privately under ~/.local/state/gimp-mcp/control.json.

Provider credentials are deliberately not copied into GIMP MCP. ChatGPT/Codex, Claude Code, Mistral Vibe, Google Antigravity and Grok Build remain owners of their OAuth state. ChatGPT/Codex, Claude Code, Mistral Vibe and Google Antigravity are queried directly. AILinux/TriForce can be configured independently with GIMP_MCP_TRIFORCE_TOKEN.

AI-client routing rule

When a user explicitly asks to draw, paint, edit or create an image with GIMP, an AI client integrating this server should route the task through GIMP MCP rather than silently substituting an unrelated image generator. Image generation may still be used as an explicit source/reference only when the user asks for it or approves a hybrid workflow.

Recommended workflow:

user prompt
  -> session_create/session_open
  -> semantic GIMP edits
  -> preview_render
  -> vision/art review
  -> further edits
  -> document_save_as + export_image

events_recent exposes the operation timeline for observers. session_list includes recovered sessions and preview locations. Sessions survive a server restart as long as their working XCF remains under the configured session root.

Architecture direction

The current production-safe path remains batch-isolated GIMP execution. The next major bridge is a persistent GIMP 3 plug-in/IPC mode for truly visible edits inside one open GIMP GUI. The semantic MCP layer, session IDs, event bus and Control Center are intentionally transport-independent so a future PersistentPluginBridge can replace or complement the current batch bridge without changing AI-facing tools.

One-shot setup and update checks

Launch ./scripts/gimp-mcp-control and open Setup / Updates. The studio can:

• check required Debian/Ubuntu/AILinux packages and configured APT candidates,

• compare selected upstream versions for GIMP, uv, MCP and PyQt6,

• install/repair system dependencies through PolicyKit after explicit confirmation,

• uv sync the project or explicitly upgrade/re-lock dependencies,

• update uv,

• fetch repository update state, and

• run pytest plus a real GIMP bridge probe.

The updater distinguishes distribution candidate from upstream latest. It does not silently replace distro packages with foreign repositories.

Persistent visible GIMP mode (0.3)

Install the bundled GIMP 3 persistent plug-in:

./scripts/install-gimp-live-plugin

Restart GIMP once. The plug-in starts automatically as a PERSISTENT GIMP procedure and creates a user-only Unix socket at:

~/.local/state/gimp-mcp/gimp-live.sock

When the socket is available, successful MCP document mutations are mirrored into a visible GIMP display. If GIMP is closed or the live plug-in is unavailable, GIMP MCP falls back to the crash-isolated batch workflow automatically.

The persistent bridge started as a visible document mirror. In 0.4 it also supports a small whitelist of direct in-process layer operations; all unsupported operations remain on the isolated batch path. Arbitrary Python execution is not exposed.

See docs/CREATIVE_AI_CLOUD.md for the shared multi-application direction, including a proposed FL Studio MCP adapter.

GIMP MCP Studio 0.4

The default Control Center view is now Studio: prompt -> selected provider/model -> persistent artwork job -> safe semantic GIMP actions -> live preview -> follow-up/export workflow. Jobs survive application restarts and recover as paused instead of silently disappearing.

Model output is treated as untrusted input. The PromptRunner accepts only structured JSON plans using a small semantic allowlist, validates arguments, rejects invented/executable tools, limits repair attempts, and never executes model-provided Python or shell commands.

Direct persistent editing currently covers layer rename, visibility, opacity and translation. The plug-in saves direct mutations back to the session XCF and flushes displays. Other operations continue through the isolated batch path and mirror back into the visible GIMP document.

See docs/QUICKSTART.md and CHANGELOG.md.

Studio plans can use $background_layer_id for the initial layer and $last_layer_id for a layer created earlier in the same plan; numeric IDs should never be invented by a model.

Live preview and export

The Control Center Live view refreshes preview.png from the selected artwork session and exposes EXPORT XCF, EXPORT PNG, and EXPORT JPG. Studio exposes compact XCF/PNG/JPG export buttons as well. XCF copies the canonical editable document.xcf; PNG/JPG are rendered by GIMP from that same document. The MCP surface also exposes export_artwork.

Autonomous diagnostics

Run ./scripts/auto-debug for a repeatable health pass. It records results in ~/.local/state/gimp-mcp/auto-debug.log and checks the test suite, native provider status, latest preview integrity, a real PNG export, the live bridge state, and the Streamable HTTP MCP handshake. GUI runtime exceptions are written to ~/.local/state/gimp-mcp/gui.log.

Vision-assisted MCP

GIMP MCP can expose a lightweight visual feedback loop for MCP-capable AI clients. Call vision_capture(session_id) after meaningful edits, then read the returned resources:

• gimp-vision://<session_id> - current PNG with a non-destructive GIMP canvas-coordinate overlay.

• gimp-timeline://<session_id> - rolling animated GIF of the most recent vision frames; re-read the same URI to obtain the newest timeline.

• gimp-vision-meta://<session_id> - structured canvas and layer geometry matching the overlay.

The coordinate contract follows GIMP/XCF canvas coordinates: (0,0) is the top-left of the image canvas, X increases right, Y increases down, and layer offsets may be outside the canvas. The overlay is never written into the artwork. When the persistent live plug-in supports vision_snapshot, the capture comes from the visible GIMP image; otherwise the current session XCF is rendered as a safe fallback. ImageMagick (magick or convert) is required for overlay/GIF rendering.

Headless creative workspaces and multi-worker AI

GIMP MCP prefers the normal visible GIMP 3 persistent bridge. If no visible GIMP bridge is reachable, it now lazily starts a private gimp -n -i GIMP 3 process and invokes the installed persistent plug-in-gimp-mcp-live procedure through GIMP's official Python/PDB batch interpreter. The headless process keeps real GIMP images open and can render vision_snapshot PNGs, so an AI can inspect the same canvas it is editing without an X11/Wayland display.

For concurrent agents, GIMP_MCP_HEADLESS_WORKERS controls a bounded pool (default 2, maximum 8). Artwork paths are deterministically assigned to a worker, allowing different sessions to execute concurrently while every session document is protected by a thread-reentrant and process-wide file lock. Multiple LLM/MCP clients may therefore share the service without writing the same XCF concurrently.

Useful expert tools:

• headless_workspace_status — visible/headless mode and worker health.

• pdb_search / pdb_describe — discover GIMP's installed Procedure Database.

• pdb_call — call a discovered PDB procedure with JSON-safe values against an artwork session. Image arguments bind to the session; layer/drawable/item arguments use MCP layer_id tattoos. Generic GFile arguments are confined to the session work directory; normal import/export should use the dedicated safe MCP tools.

• filter_list / filter_describe / filter_apply — GEGL discovery and non-destructive Gimp.DrawableFilter editing.

• vision_capture plus gimp-vision://, gimp-vision-meta:// and gimp-timeline:// — coordinate-aware visual feedback for models.

The headless pool is a fallback, not a replacement for interactive GIMP. If a visible bridge appears, new bridge requests prefer it automatically.

systemd service / Control Center

The recommended server runtime is the per-user gimp-mcp.service. The Control Center can install or repair it, enable/disable login autostart, start, stop and restart it, and show its journal. The service is independent from the GUI: closing the Control Center does not stop MCP or its headless GIMP workers. Runtime bind/auth/GIMP settings are loaded from ~/.local/state/gimp-mcp/control.json each time the service starts.