GimpMCP

An MCP server that lets an LLM (Claude Code, Claude Desktop, etc.) drive a running GIMP instance: images, layers, selections, gradients, text, transforms, color adjustments, any GEGL filter, or arbitrary Script-Fu (Scheme) code against GIMP's PDB.

How it works

GIMP ships a plug-in called plug-in-script-fu-server that turns GIMP into a persistent TCP server: you send it Scheme source over a socket and it sends back the printed result. This project exposes MCP tools that build the right Scheme snippet, send it over the socket, and parse the reply.

Full GIMP access comes in three layers:

1. Curated tools (below) for the common operations, with clean parameters.

2. apply_gegl_filter — applies any of GIMP's ~400 GEGL filters by name (gegl:pixelize, gegl:oilify, gegl:lens-flare, ...) with keyword params.

3. run_script_fu — runs arbitrary Scheme against the full PDB (~2,000 procedures), with search_gimp_api to discover what exists.

Related MCP server: mcp-toolbox

Live UI mode (watch edits happen in GIMP)

If the Script-Fu server runs inside your visible GIMP window, every edit is shown live on screen. To enable this, in GIMP:

Filters ▸ Development ▸ Script-Fu ▸ Script-Fu Server (older builds: Filters ▸ Script-Fu ▸ Start Server), keep IP 127.0.0.1 and port 10008, click Start.

If no GIMP is running at all, the first tool call auto-starts a headless GIMP instead (fast, but edits are invisible). If GIMP's GUI is open but the server isn't started, tools refuse with a hint rather than silently editing in an invisible instance. gimp_status reports which mode you're connected to.

Setup

1. Install GIMP 3.0 if you haven't already: https://www.gimp.org/downloads/

2. From this directory:

   python -m venv .venv
   .venv\Scripts\pip install -e .

3. (Optional) If auto-detection can't find your GIMP install, set the GIMP_EXECUTABLE environment variable to the full path of gimp-console-3.0.exe (typically under C:\Program Files\GIMP 3\bin\).

Register with Claude Code

Add to your MCP config (e.g. via claude mcp add or your .mcp.json):

{
  "mcpServers": {
    "gimp": {
      "command": "C:\\path\\to\\GimpMCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "gimp_mcp.server"]
    }
  }
}

Then ask Claude things like "open C:\photos\cat.png in GIMP, resize it to 800x600, and export it as cat_small.jpg".

Tools

Example

examples/poster.py builds a complete layered poster (gradient background, glowing shapes, positioned text with a screen-mode glow) live in a visible GIMP window, then exports a PNG — a good tour of the API.

Platform support

Developed and fully verified on Windows + GIMP 3.0.8 (both the per-user %LOCALAPPDATA%\Programs\GIMP 3 and system-wide Program Files install locations are auto-detected). macOS and Linux path detection is included but untested — set GIMP_EXECUTABLE to your gimp-console binary if detection fails, and please report what you find. GIMP 2.10 is not supported: the curated tools target GIMP 3.0's renamed PDB API (see below).

Verified against GIMP 3.0.8

Every tool above has been exercised end-to-end against a real, running GIMP 3.0.8 (Windows) Script-Fu server — see smoketest.py. GIMP 3.0 renamed or removed a surprising number of PDB procedures compared to 2.10; here's what changed and what this project uses instead:

The last one is the big one: GIMP 3.0's Script-Fu no longer exposes most GEGL filters as individual named procedures. Anything not covered by a curated tool here can likely still be reached via gimp-drawable-merge-new-filter with the right gegl: operation name — check GIMP's share/gimp/3.0/scripts/*.scm files (installed alongside GIMP) for real, working examples, or use (oblist) in run_script_fu to list every currently-bound Script-Fu symbol and grep for what you need.

If you're on a different GIMP version and something breaks, GIMP's own Script-Fu console (Filters > Script-Fu > Console) plus (defined? 'some-name) is the fastest way to check whether a procedure exists before wiring it up.

Protocol notes (for hacking on this further)

src/gimp_mcp/client.py implements the raw binary framing:

• Request: [0x47][len_hi][len_lo][script bytes]

• Response: [0x47][err_code][len_hi][len_lo][result bytes]

err_code is 0 on success, non-zero on Script-Fu evaluation errors. Length fields are 16-bit big-endian, so a single script is capped at 65535 bytes.

Every Script-Fu PDB call returns a list of its results even when there's only one, hence the frequent (car ...) in the generated scripts.

License

MIT — see LICENSE.