Edit images in GIMP by talking to your AI assistant.

Overview

GIMP Studio MCP lets your AI assistant work inside GIMP 3.x — the free, open-source image editor — instead of you clicking through menus. Point it at an image and ask for what you want: "crop this to the artwork and export a transparent PNG," "knock out the white background but keep the white in the logo," "size this to print 12 inches wide at 300 DPI." It does the steps in GIMP and hands you the result. (MCP is simply the standard that lets AI assistants connect to outside tools like this one — you don't need to understand it to use this.)

It can see its own work — it renders a preview back to the assistant so it can check the result and fix it, rather than editing blind. Every action returns a structured result, so when something goes wrong you get a clear error instead of a silent failure — you can see what happened and fix it. Risky edits can be wrapped in a checkpoint you can roll back. It attaches to a GIMP you already have open, or spins one up in the background automatically — the same tools work either way. It was built for a working print shop's DTF (direct-to-film) pipeline, so print sizing and transfer prep are first-class, not afterthoughts.

What you can do

• Edit and create images — open, crop, scale, layers, masks, selections, paint, text, colors, filters, and export, all by asking
• Remove backgrounds — crisp one-color cutouts, soft color-to-alpha, and garment-aware shirt-color knockout tuned per garment, plus edge-aware refinement for soft or hair-fine edges where the background is not one flat color
• Prep for print / DTF — set the physical size in inches at a target DPI, trim to the artwork, add a white underbase, and export a transparent, print-ready PNG
• Gang up a sheet — pack multiple designs onto one print sheet at 300 DPI and export it
• See the result — the assistant can pull a preview of the canvas (or any region) to verify what it did before you do
• Work safely — checkpoint and restore any image before a risky edit, and a structured result on every step so failures are caught, not silent
• Built-in guidance — the server ships a concise orientation to the assistant on connect, so it knows the right workflow (and the common pitfalls) from the start

Requirements

• GIMP 3.x installed (verified on 3.0.4 and 3.2.4; GIMP 2.x is not supported). Works on Windows, macOS, and Linux.
• Python 3.10+ installed and on your PATH — pipx and the server both run on it. Most macOS and Linux machines already have it; on Windows, get it from python.org and tick "Add python.exe to PATH" in the installer.
• An MCP-compatible AI client — the app your assistant runs in (e.g. Claude Desktop, Claude Code, Cursor, Windsurf, VS Code)
• A one-time install of the GIMP-side bridge, done with gimp-mcp install-plugin (Step 2 below)

Installation

No programming needed — but you will paste a few commands into a terminal and add one block to your AI client's settings. Here's the whole thing, start to finish.

Step 1: Install the server

This installs the gimp-mcp command you'll use in the next two steps:

pipx install twelvetake-gimp-studio-mcp

If pipx warns that the command isn't on your PATH, run pipx ensurepath, then close and reopen your terminal before continuing. Using plain pip instead? pip install twelvetake-gimp-studio-mcp.

Prefer to install straight from source? pipx install git+https://github.com/TwelveTake-Studios/gimp-studio-mcp, or clone the repo and run pip install -e .

Step 2: Install the GIMP-side bridge

GIMP needs a small plug-in so the server can talk to it. Install it once:

gimp-mcp install-plugin

Then restart GIMP (or start it, if it's closed) so it loads the new plug-in — the bridge starts automatically whenever GIMP is open. Now confirm everything is wired up:

gimp-mcp doctor

doctor checks the install, finds your GIMP, and round-trips the connection; add --headless to also test the background mode. You only install the plug-in once.

Step 3: Add it to your AI client

Nearly every MCP client uses the same JSON — an mcpServers entry with a command and its args. Add this to your client's MCP configuration:

{
  "mcpServers": {
    "gimp": {
      "command": "gimp-mcp",
      "args": ["serve"]
    }
  }
}

Where you put it depends on your client:

• Claude Desktop — Settings → Developer → Edit Config (opens claude_desktop_config.json); paste the block above.
• Claude Code — skip the JSON and just run: claude mcp add gimp -- gimp-mcp serve
• Cursor — Settings → MCP → Add, or paste the block above into ~/.cursor/mcp.json (everywhere) or .cursor/mcp.json (one project) — same shape.
• Windsurf — in the Cascade panel, click the MCP icon → Configure, or edit ~/.codeium/windsurf/mcp_config.json — same shape.
• VS Code — Command Palette → "MCP: Add Server," or edit .vscode/mcp.json. VS Code is the one exception to the shape — it uses a top-level servers key with "type": "stdio":

{
  "servers": {
    "gimp": {
      "type": "stdio",
      "command": "gimp-mcp",
      "args": ["serve"]
    }
  }
}

Using a different client? Add the same command and args wherever it lists MCP servers, and check its MCP docs for the exact spot. After adding it, fully quit and reopen your client.

Optional settings

These are environment variables — named settings the server reads when it starts. The simplest way to set them is right in the config from Step 3, in an env block (in VS Code, put the env block inside the servers entry instead):

"gimp": {
  "command": "gimp-mcp",
  "args": ["serve"],
  "env": {
    "GIMP_MCP_HEADLESS": "1"
  }
}

• GIMP_MCP_HEADLESS — always run GIMP in the background instead of attaching to a window you have open
• GIMP_MCP_NO_EXEC — leave out the raw gimp_exec tool (arbitrary code in GIMP); every other tool still works. See Security.

Troubleshooting

• "gimp-mcp: command not found" (or "not recognized")? pipx's app folder isn't on your PATH yet — run pipx ensurepath and open a fresh terminal.
• Server doesn't show up in your client? Fully quit and reopen it after editing the config, and check the config is valid JSON (a stray trailing comma is the usual culprit).
• Not sure it's connected? Run gimp-mcp doctor in a terminal — it checks the install and round-trips the GIMP connection.
• Tools don't appear, or GIMP doesn't respond? Make sure you ran gimp-mcp install-plugin and then restarted GIMP so the bridge loads.
• Edited the server or updated it, but tools look the same? The server doesn't reload mid-session — fully restart your AI client.

Working with your images

The server drives GIMP on files on your computer — it doesn't reach out to anything else. There are two ways it runs, and the same tools work in both:

• Live — if you have GIMP open, it attaches to that window, so you watch the edits happen on the canvas.
• Background (headless) — if GIMP isn't open, it starts one quietly in the background, does the work, and exports the result. Nothing pops up.

A typical round trip:

1. Point your assistant at an image — paste its full path or drag it into the chat, or just work on whatever's open in GIMP.
2. Ask for the change in plain language; the assistant does it and can pull a preview to confirm.
3. It exports the result to a file you name (it works on a copy for exports, so your open image isn't flattened or overwritten behind your back).

It only touches the images and files you point it at, and it runs on your own machine — see Security below.

Available tools (119)

You don't call these directly — you ask in plain language and your assistant picks the right ones. They span 13 groups:

Tools are self-describing through your MCP client, and there's a raw gimp_exec escape hatch for anything a dedicated tool doesn't cover — so a missing tool is rarely a hard stop.

Usage examples

Just talk to your assistant. A few of the things you can ask:

General editing

Open logo.png and tell me its size, layers, and DPI

Add a 12px white outline to the text layer

Auto-crop to the artwork, then export a transparent PNG

Cut out the white background, keeping the white inside the logo

Show me the current canvas

DTF & print prep

Knock out the black shirt color behind this artwork

Size this to print 12 inches wide at 300 DPI

Clean this up for DTF and export a transparent 300-DPI PNG

Gang up 12 copies of this design onto a 22-inch sheet at 300 DPI

knockout_background is garment-aware: name a shirt color (black, navy, heather gray, red, and more) and it picks the removal technique and tolerance tuned for that garment. Ask for the preset list to see the catalog. If the shirt color also appears inside your art, say so and ask it to remove only the background around the design, so those parts survive.

FAQ