gimp-mcp

An MCP server that drives GIMP 3 for scripted image editing: crop, resize, aspect-ratio fitting, light colour touch-up, dimension-spec validation, and batch processing across a folder.

Built and verified on Windows with GIMP 3.2.4, using GIMP 3's GObject Introspection Python API (gi.repository.Gimp) rather than the old 2.x Script-Fu interface.

---

What it is for

Any workflow where images need the same deterministic treatment applied repeatedly and you would rather describe it than click through it:

• crop a photo to a target aspect ratio, or to the largest centred square
• resize a folder of images so the longest edge is at most 2000px
• check whether images meet a size/orientation requirement before publishing
• apply one crop-and-resize pipeline across a whole shoot in one pass

The one thing that will bite you: EXIF orientation

Photos from phones and many cameras are frequently stored landscape with an EXIF orientation tag telling viewers to rotate them. A photo everyone sees as 3000x4000 portrait may be stored as 4000x3000.

GIMP's non-interactive loader does not apply that tag. A naive "crop to square, centered" therefore crops the wrong axis and produces a sideways image — while still reporting plausible-looking dimensions, so nothing looks obviously broken until you open the output.

Every load in this project goes through load_image(), which calls Gimp.Image.policy_rotate() first, so all geometry — and every dimension this server reports — is in displayed orientation, i.e. what a viewer actually sees. This is covered by a test.

---

Architecture

Two execution backends, one shared operation runtime:

                    ┌───────────────────────────────┐
  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 writes a runtime_path.txt pointer next to the installed plug-in rather than copying gimp_runtime.py, so exactly one copy of the operation code exists on disk.

Backend choice. headless is the default and is what all batch and deterministic work uses — it needs no open GIMP and is the reliable path. bridge is for live work on a document you already have open. Both are verified to produce pixel-identical output.

Why TCP and not D-Bus

Existing live-GIMP-control projects use D-Bus, which does not exist on Windows. A loopback TCP socket achieves the same thing and is cross-platform. It binds 127.0.0.1 only and is never exposed to the network.

---

Install

Requires GIMP 3.x (developed against 3.2.4) and the mcp Python package.

Note on the mcp dependency. This targets the mcp 1.x SDK and is pinned to mcp>=1.0,<2. Version 2.0 removed mcp.server.fastmcp and renamed FastMCP to MCPServer; porting to it is not done yet, and an unpinned install picks up 2.x and fails at import.

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

The bridge plug-in is only needed for the live control tools. The batch and single-image tools work without installing anything into GIMP.

Plug-in location

install_plugin.py discovers whatever GIMP 3.x config directories actually exist rather than hardcoding a version. On Windows that is:

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

Note it is the versioned directory (3.2 for GIMP 3.2, not 3.0), and GIMP 3 requires each plug-in to sit in a folder whose name matches the .py file. On Linux and macOS the installer looks in ~/.config/GIMP/3.x/ and ~/Library/Application Support/GIMP/3.x/ respectively.

Register the MCP server

Installing the package provides a gimp-mcp console script, which is the tidiest thing to register because it does not depend on a working directory:

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

With Claude Code, the equivalent one-liner is:

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

Running the module directly works too, if mcp is importable in that interpreter:

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

Optional environment variables:

Variable	Purpose
GIMP_CONSOLE	Full path to gimp-console-3.exe if it is not auto-detected
GIMP_MCP_BACKEND	headless (default) or bridge
GIMP_MCP_BRIDGE_PORT	Bridge port, default 50472

---

Tools

Inspection

Tool	Purpose
gimp_status	Check GIMP is reachable; reports both backends. Start here if something is wrong.
inspect_image	Dimensions, layers, orientation. Dimensions are as displayed.
check_image_spec	Validate against a dimension spec; pass/fail with measured dimensions and a plain-language reason.

Single image

Tool	Purpose
crop_image	Exact pixel rectangle. Rejects out-of-bounds rather than silently clamping.
crop_square	Largest square; anchor = center/top/bottom/left/right/corner.
crop_to_aspect	Target ratio (1.0 square, 1.3333 for 4:3, 1.7778 for 16:9), max area.
resize_image	By width, height, or max_edge. Aspect preserved by default.
adjust_image	Brightness/contrast, restricted to -0.5..0.5.
fit_to_spec	One shot: fix orientation by cropping, upscale to a minimum, downscale to a maximum, optional touch-up.
process_image	Custom operation pipeline in one pass (one JPEG re-encode).

Batch

Tool	Purpose
batch_process	Arbitrary pipeline over a folder.
batch_fit_to_spec	Conform a whole folder to one dimension spec.
batch_check_image_spec	Read-only audit; triage before editing.

A whole batch runs inside one GIMP invocation. GIMP's console takes several seconds to start, so spawning per file would be slow — measured at ~2.4x cheaper per file for a small folder, and the saving grows with folder size. A file that fails does not abort the run; it lands in errors and the rest continue.

Live control (needs the bridge plug-in)

Tool	Purpose
live_list_images	What is open in the running GIMP.
live_screenshot	Flattened snapshot of the canvas, so you can see and iterate.
live_run_python	Arbitrary Python in the live context; assign to result.
live_stop_bridge	Stop the bridge, leave GIMP open.

Start the bridge in GIMP: Filters > Development > Start MCP Bridge.

---

Image specifications

check_image_spec, fit_to_spec and their batch equivalents share one spec model. Every constraint is optional — 0 means no limit, and orientation any means no orientation requirement.

Field	Values
min_width, min_height	pixels, 0 for no minimum
max_width, max_height	pixels, 0 for no maximum
orientation	any, square, landscape, portrait, square_or_landscape, square_or_portrait

fit_to_spec satisfies a spec in three ordered steps: crop to correct the orientation, upscale to reach the minimum, downscale to respect the maximum. Constraints already satisfied leave the framing untouched.

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

Colour adjustment is deliberately limited

adjust_image restricts brightness/contrast to -0.5..0.5 and rejects anything outside it rather than clamping. Values beyond roughly ±0.15 visibly change the character of a photo, which matters when an image needs to represent a real subject faithfully. There is intentionally no saturation boost or "auto enhance".

---

Verification

Run the suite:

python -m pytest tests/ -v

Tests that need real images are skipped unless you point them at some:

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 should be an independently produced centred square crop of GIMP_MCP_TEST_IMAGE — cropped by hand in GIMP, for example. The headline test asserts that crop_square reproduces that reference, rather than merely running without error.

On the reference photo used during development (a 4000x3000 JPEG with EXIF orientation 6, displaying as 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%

That residual is JPEG re-encode noise — re-encoding alone gives ~0.5 mean — not a geometry difference, and both backends agree exactly.

The suite also covers displayed-orientation reporting, orientation and minimum-size specs, out-of-bounds crops being rejected, out-of-range adjustments being rejected, brightness moving pixels the right way, chained pipelines, aspect-ratio cropping, batch across a folder, the read-only audit, clear errors for missing files, and a full pass over the real MCP stdio protocol.

---

Troubleshooting

gimp-console not found — set GIMP_CONSOLE to the full path of gimp-console-3.exe.

Bridge tools fail with "Could not reach the GIMP bridge" — GIMP is not open, or the bridge was not started. Run Filters > Development > Start MCP Bridge. gimp_status shows both backends at once.

The menu item is missing after installing — restart GIMP; it only scans plug-ins at startup. Confirm the layout is plug-ins/gimp-mcp-bridge/gimp-mcp-bridge.py (the folder name must match the file name).

Diagnosing the plug-in — a GIMP plug-in is a separate process whose stderr is invisible when GIMP runs as a GUI app on Windows. The bridge writes to bridge.log next to the installed plug-in.

A colour-profile dialog blocks GIMP on startup when opening an image with an embedded profile in GUI mode. It does not appear in headless mode, which is another reason batch work uses the headless backend.

Batch timed out — the default is 600s for the whole run; very large folders may need more.

---

Known limitations

• Live control is only lightly exercised. It is verified working (open an image, list, screenshot, edit live, and crop through the bridge with output identical to headless), but it has had far less use than the headless path. Treat headless as the trustworthy one.
• The bridge executes arbitrary Python by design. It is loopback-only and started manually rather than automatically, but anything that can reach localhost on the machine can drive GIMP while it is running. Stop it when not in use.
• Bridge start blocks its own plug-in process — that is what keeps it alive. It does not freeze GIMP's UI, but GIMP shows the plug-in as running.
• The GUI menu item itself is not automated-test covered. The procedure it invokes is verified; the click path is not.
• Only Windows is verified. The code paths are cross-platform and the installer handles Linux/macOS config directories, but neither has been tested.
• The mcp 2.x SDK is not supported yet -- see the note under Install.
• No AI background removal or style transfer. Some comparable projects advertise these without a working implementation behind them; they are deliberately not claimed here.

Notes on prior art

The split between a GIMP-side plug-in exposing a bridge and a standalone MCP server process that connects to it as a client is a natural shape for this problem and is used by other GIMP MCP projects. Batch processing and preset-style pipelines are common to several. Live-canvas control exists elsewhere via D-Bus, replaced here with loopback TCP for Windows support. No code was copied from any of them; the Windows specifics — the real plug-in path, the plug-in process lifetime, the run-callback signature, and the EXIF behaviour — were established directly against GIMP 3.2.4.

License

MIT — see LICENSE.