GIMP Studio MCP

GIMP Studio MCP

A TwelveTake Studios project.

Listed in the MCP Registry as mcp-name: com.twelvetake/gimp-studio-mcp.

GIMP Studio MCP is a Model Context Protocol server that enables AI assistants to edit images in GIMP 3. Every tool returns a structured result with captured errors, and checkpoints restore an earlier state of the image on request. It includes tools for print and DTF (direct-to-film) transfer production.

119 tools across 13 groups, each tested against a real GIMP instance.

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 server

It is built around print and DTF production: physical dimensions at print resolution, garment-color knockout, and transparent PNG output ready for film. Every tool returns a structured result, so the assistant does not need to write GIMP Python for routine edits.

The design rules (every tool follows these)

1. Structured returns: { ok, result, stdout, warnings, error }; output is never lost, even on error.
2. Raw exec stays: the universal escape hatch (gimp_exec) survives, with proper capture. (Opt out with GIMP_MCP_NO_EXEC=1; see Security model.)
3. Compat / quirk layer: one module handles GIMP 3 differences and known issues.
4. Mode-agnostic tools: work identically whether GIMP is live (visible canvas) or headless.
5. Vision-first: get_bitmap returns a viewable image the agent can actually see (with region/scale/byte-budget), for self-verification.
6. Safety by default: checkpoint / restore around destructive ops.
7. Validated params everywhere.
8. 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.

Capability areas (119 tools)

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.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     # copies the bridge into GIMP's plug-ins dir
gimp-mcp doctor             # verify install + GIMP exe + bridge reachability

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	Always run a headless GIMP (spawn gimp -i) instead of attaching to a running one (1/true/yes/on).
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.
GIMP_MCP_EXE	Path to GIMP's gimp-console executable, for an installation the server does not find automatically.
GIMP3_DIRECTORY	GIMP's own variable for a non-default GIMP profile folder. gimp-mcp install-plugin installs the bridge there and gimp-mcp doctor checks it there.
GIMP_MCP_OPERATION_TIMEOUT	Seconds a single GIMP operation may run before it returns a timeout error (default 120).
GIMP_MCP_START_TIMEOUT	Seconds to wait for a headless GIMP to start (default 60).
GIMP_MCP_CONNECT_TIMEOUT	Seconds to wait when connecting to GIMP (default 10).

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: [email protected]