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.

_{A real, unedited session at 2× speed: one prompt in Claude Code, everything else done by GIMP through gimp-mcp. Full-quality video (1080p, real time).}

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."

What it can do

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.