gimp-mcp

gimp-mcp

Tell your AI assistant what you want, and watch it happen in GIMP. gimp-mcp connects Claude, Codex, Cursor, VS Code or any other MCP client to the GIMP window you already have open: it opens files, builds layers, sets editable text, makes selections, applies filters and exports, step by step, right in front of you.

Quickstart

gimp-mcp runs on Linux, macOS and Windows. You need GIMP 3.2+, uv and an MCP client. On Ubuntu 26.04:

sudo apt install -y gimp python3-gi gir1.2-gimp-3.0   # GIMP 3.2+ (other distributions and Flatpak: see below)
uvx gimp-mcp setup                                    # installs the GIMP plug-in, adds the server to your MCP clients
uvx gimp-mcp doctor                                   # after (re)starting GIMP: every check should be [ok]

Then ask your assistant: "Use GIMP to create a 1280×720 image with the title 'Hello' and export it to ~/hello.png".

• macOS and Windows: install GIMP 3.2 from gimp.org, then run the same uvx gimp-mcp setup and uvx gimp-mcp doctor (install).
• Arch, Debian 14, Fedora 44, openSUSE Tumbleweed, Alpine 3.24 and GIMP from Flathub: see compatibility.
• Step by step for Claude Code, Claude Desktop, VS Code and Cursor and any other MCP client (Codex, Zed…).
• Something wrong? uvx gimp-mcp doctor says what and how to fix it (troubleshooting).

Why gimp-mcp

Your GIMP, live. The assistant works in the GIMP you have open, not in a hidden copy. Every layer it adds shows up in the Layers panel, and you can take over with the mouse at any time.

Results you can keep editing. Titles stay editable text layers, each step can go on its own layer, blurs and color corrections can be editable filters, and the XCF keeps all of it. The assistant gives you a starting point, not a flattened PNG.

It checks its own work. Previews come back to the model as images, so it can see the result, fix what looks off and only then export. Checkpoints let it try an idea and go back to an earlier state when it doesn't work out.

Local and locked down. No network port: one Unix socket that only you can open, a fresh token at every GIMP start, a fixed set of operations, and an allowlist for the GIMP procedures it may call (no eval, no Script-Fu passthrough). Details in the security model.

Set up in one command. gimp-mcp setup finds GIMP (distribution package or Flatpak), installs the plug-in and adds the server to Claude Code, Claude Desktop, VS Code and Cursor, asking before it changes any file.

Things to ask

• "Open ~/Pictures/team.jpg, crop it to a centered square and export a 512 px avatar."
• "Make a 1200×630 social card for my blog post 'Shipping on Fridays', dark background, title on the left."
• "Brighten only the background layer of poster.xcf and keep the original underneath, hidden."
• "What's in ~/design/flyer.xcf? List the layers, the hidden ones and the fonts used."
• "Blur the license plate in car.jpg and save a copy next to it."

Use cases

Typical GIMP jobs done end to end through MCP, each with a scripted version checked in CI on Linux, macOS and Windows, and an agent version (one plain-language request) in the evaluation suite:

• Restore an old scanned photo: straighten, crop the scanner bed, heal dust and scratches, restore contrast, reduce grain, 16-bit TIFF for print (walk-through).
• Product photo for an online store: cut out without losing pixels, soft shadow on pure white, centered square, JPEG and WebP in three sizes with an sRGB profile (walk-through).
• Social media kit: one design in four formats (post, story, banner, thumbnail) with safe-area guides and an editable headline (walk-through).
• Tutorial screenshot: callouts and arrows, private data pixelated beyond recovery, metadata removed (walk-through).
• Photos for a website: a folder upright, resized, watermarked, GPS removed, WebP and JPEG, the corrupt file reported (walk-through).
• Animated sticker: frames with timing and disposal, optimized GIF and animated WebP under a size budget (walk-through).
• Print-ready flyer: A5 at 300 dpi with bleed, trim and safe-margin guides, PDF and TIFF at print size (walk-through).
• Sky replacement: a new sky masked in, the foreground graded with an editable filter, no halo (walk-through).
• YouTube thumbnail from one photo, with an editable title (guide).

What it can do

Look	list open images, inspect layer trees and items, render previews the model can see
Files	create, open, save XCF, export PNG and JPEG with options, close
Layers	add, import, duplicate, group, reorder, rename, opacity, blend modes, visibility
Shape	resize image or canvas, crop, scale, rotate, flip, move
Select	rectangles and ellipses (add, subtract, intersect, feather), invert, layer masks
Paint	fills, lines and paths, rectangles and ellipses
Text	editable text layers: font, size, color, alignment, spacing
Adjust	brightness/contrast, hue/saturation, blur, as destructive or editable filters
History	undo groups (one Ctrl+Z in GIMP) and checkpoints the assistant can restore
Everything else	about 420 more GIMP procedures, allowlisted (procedures toolset, opt-in)

54 tools in all, grouped into toolsets so your client only loads what it needs: see the tool reference and the coverage matrix.

How it works

 Claude / Codex / Cursor / …            gimp-mcp serve                 GIMP 3.2
 ───────────────────────────  MCP   ─────────────────────  Unix   ─────────────────────────
  "make the colors pop"      stdio   validates, maps ids  socket   gimp-mcp-bridge plug-in
                            ──────▶  to GIMP operations  ──────▶   runs them in your session

gimp-mcp setup copies a small Python plug-in into your GIMP profile. GIMP starts it with the application, and it serves its local socket while GIMP runs. The MCP server (uvx gimp-mcp serve, started by your client) talks to it. Also works with a headless GIMP for scripts and CI. More in the architecture notes.

Documentation

• Installation reference (manual install, upgrade, uninstall) · MCP clients · troubleshooting · compatibility
• Tool reference · coverage matrix · scripted demo walk-through
• Architecture · bridge protocol · security · decisions
• Testing · releasing · recording the demo video · GIMP behaviour notes · changelog

Also listed in the official MCP registry as io.github.mhbxyz/gimp-mcp. MIT licensed.