GIMP Studio MCP
A TwelveTake Studios project.
Listed in the MCP Registry as mcp-name: com.twelvetake/gimp-studio-mcp.
A comprehensive GIMP 3.x MCP server that gives an AI agent full, reliable control of GIMP — with structured returns, real error capture, a GIMP-3 compatibility layer, safety checkpoints, and print/DTF-aware tooling.
119 tools across 13 groups, each behaviorally tested against a real (headless) GIMP. Built for a working print shop's DTF (direct-to-film) pipeline, not as a thin API wrapper.
Status: beta. Tested on GIMP 3.2.4, headless and live. Releases up to 0.3.3 were also tested on GIMP 3.0.4.
Why this exists
Other GIMP MCP servers exist. This one is built around print and DTF production: real inches at print DPI, shirt-color knockout and transparent PNGs ready for film. Every tool returns a structured result, so the agent doesn't write GIMP Python by hand for everyday edits.
- Structured returns —
{ ok, result, stdout, warnings, error }; output is never lost, even on error.
- Raw
exec stays — the universal escape hatch (gimp_exec) survives, with proper capture. (Opt out with GIMP_MCP_NO_EXEC=1 — see Security model.)
- Compat / quirk layer — one module owns GIMP-3 gotchas so nobody relearns them per session.
- Mode-agnostic tools — work identically whether GIMP is live (visible canvas) or headless.
- Vision-first —
get_bitmap returns a viewable image the agent can actually see (with region/scale/byte-budget), for self-verification.
- Safety by default —
checkpoint / restore around destructive ops.
- Validated params everywhere.
- Print-aware throughout — DPI / inches are first-class; DTF output is a headline feature.
Architecture (hybrid, day one)
Live and headless differ only in who launches GIMP, not how we talk to it — so it's one bridge:
- Live: a persistent GIMP extension (installed by
gimp-mcp install-plugin) starts on launch and publishes a loopback endpoint; the MCP server auto-attaches to the running GIMP, canvas visible.
- Headless: if no live GIMP is found, the server spawns a long-running
gimp -i and loads the same bridge.
Both speak one loopback-TCP, length-prefixed-JSON, token-authenticated protocol; pixel export works in both.
| Group | Tools | What it covers |
|---|
| Session | 5 | health/status, open-image list, active-image switch, raw gimp_exec, namespace reset |
| Document | 4 | new/open image, metadata, alpha-safe export (preserves transparency) |
| Layers | 18 | create/duplicate/delete/reorder/move, opacity, blend mode, groups, merge, content-offset + seam-check (tileable textures) |
| Masks & Alpha | 9 | add/apply/remove masks, alpha add/lock, alpha↔selection, luminance→alpha, color→alpha (soft) + cutout_color (crisp hard knockout) |
| Selections | 15 | rect/ellipse/by-color/fuzzy/from-path/from-alpha, grow/shrink/feather/border, invert, to-channel, foreground_select (edge-aware subject/matting) |
| Paint | 10 | pencil/paintbrush, bucket fill, gradient, stroke, fg/bg + brush + opacity context |
| Text | 5 | create/edit text layers, props, outline, font check/substitute |
| Color & Tone | 10 | brightness/contrast, levels, curves, hue/sat, color balance, desaturate, posterize, invert, threshold, normalize (auto stretch-contrast) |
| Filters & Effects | 4 | gaussian blur, unsharp mask, drop shadow, generic GEGL apply_filter |
| Print / DTF | 13 | white underbase, edge choke/spread, trim-to-content, knockout_background (garment-aware), clean-for-DTF, halftone separation, gang sheet (22″@300), DTF PNG export, geometry/bleed |
| Color Management | 7 | assign/convert ICC profiles, grayscale/RGB conversion, profile inspect |
| Analysis | 12 | get_bitmap (viewable preview), histogram (perceptual, matches levels), color-at, region read, metadata, op describe, GEGL/procedure listing |
| Safety | 7 | checkpoint/restore (scriptable rollback), undo groups, list checkpoints |
Tools are self-describing through your MCP client; describe_op and list_* tools enumerate ops and resources at runtime.
Requirements
- GIMP 3.x (tested on 3.0.4 and 3.2.4)
- Python 3.10+ (for the MCP server)
- An MCP-compatible AI assistant (e.g. Claude Code / Claude Desktop)
Installation
1. Install the server
From PyPI:
pipx install twelvetake-gimp-studio-mcp
Or from a clone:
git clone https://github.com/TwelveTake-Studios/gimp-studio-mcp
cd gimp-studio-mcp
pip install -e .
2. Install the GIMP-side bridge
gimp-mcp install-plugin
gimp-mcp doctor
Restart GIMP (or it loads on next launch). The bridge auto-starts as a persistent extension.
3. Register with your MCP client
Add to your client's MCP config (e.g. .mcp.json):
{
"mcpServers": {
"gimp": {
"command": "gimp-mcp",
"args": ["serve"]
}
}
}
The server attaches to a running GIMP if one is available, and otherwise spawns a headless GIMP automatically. Set GIMP_MCP_HEADLESS=1 to always run headless.
Quick start
General editing
"Open logo.png and tell me its size and layers"
"Add a 12px white outline to the text layer"
"Auto-crop the image to its content, then export a transparent PNG"
"Show me the current canvas" → get_bitmap returns a viewable preview
DTF (direct-to-film) — the headline workflow
"Knock out the black shirt color behind this artwork" → knockout_background, garment-aware
"Add a white underbase choked 2px so it doesn't peek" → white_underbase + edge_choke
"Clean this up for DTF and export a 300-DPI transparent PNG"
"Gang up 12 copies of this design onto a 22-inch sheet at 300 DPI"
knockout_background is garment-aware: pass a shirt= preset (black, navy, heather_gray, red, …) and it picks the right removal technique (color-to-alpha for dark garments where black is the shirt showing through, hard select-and-clear for light/saturated ones). list_shirt_presets shows the catalog.
Security model
This server runs on the same trust boundary as the local user. Installing it grants any attached AI agent the ability to drive GIMP on your machine — and, through gimp_exec, to run arbitrary Python in GIMP's process. That is intended for a single-user workstation; it is not a sandbox.
- Loopback only + token. The bridge listens on
127.0.0.1 with an ephemeral port and a per-session token. It is not exposed to the network.
gimp_exec is arbitrary host code execution by design. A malicious or prompt-injected instruction (for example, hidden in an image you ask the agent to open) could reach gimp_exec. Only attach trusted agents and trusted content.- Disable switch. Set
GIMP_MCP_NO_EXEC=1 to skip registering gimp_exec entirely; the other 118 structured tools still work.
See SECURITY.md for the full threat model and reporting instructions.
Environment variables
| Variable | Effect |
|---|
GIMP_MCP_HEADLESS | Force headless GIMP (spawn gimp -i) instead of attaching to a running one. |
GIMP_MCP_NO_EXEC | Skip registering the raw gimp_exec host-code-exec tool (1/true/yes/on). |
GIMP_MCP_DISABLED | The in-GIMP bridge acks and does not serve. |
GIMP_MCP_ENDPOINT_FILE | Explicit endpoint-file path (advanced / headless). |
GIMP_MCP_PORT | Pin a bridge port instead of an ephemeral one. |
Troubleshooting
Run gimp-mcp doctor first — it checks the install, locates the GIMP executable, and round-trips the bridge. Add --headless to also spawn a headless GIMP and verify a full round-trip.
- "Bridge not reachable" with GIMP open: make sure you ran
gimp-mcp install-plugin and restarted GIMP so the bridge extension loaded.
- Edited the server but tools look unchanged: the MCP server does not hot-reload — restart your MCP client session.
License
MIT — see LICENSE.
TwelveTake Studios LLC
Website: twelvetake.com
Contact: contact@twelvetake.com