GIMP Studio MCP

GIMP Studio MCP

A TwelveTake Studios project.

[PyPI] [CI] [Python] [Tools] [License: MIT] [Buy Me a Coffee] [Ko-fi]

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)

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-mcpcd gimp-studio-mcppip install -e .

2. Install the GIMP-side bridge

gimp-mcp install-plugin     # copies the bridge into GIMP's plug-ins dirgimp-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

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]