How do I install GIMP Studio MCP?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does GIMP Studio MCP need an API key?

No required environment variable is listed on this record.

What transport does GIMP Studio MCP use?

GIMP Studio MCP runs locally over stdio.

When was GIMP Studio MCP last checked?

Last checked 2026-11-08. Enables AI assistants to edit images in GIMP 3, with tools for print and DTF transfer production.

GIMP Studio MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx twelvetake-gimp-studio-mcp==0.4.0

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add com.twelvetake-gimp-studio-mcp -- uvx twelvetake-gimp-studio-mcp==0.4.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "com.twelvetake-gimp-studio-mcp": {4      "command": "uvx",5      "args": [6        "twelvetake-gimp-studio-mcp==0.4.0"7      ]8    }9  }10}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.4.0
Last checked

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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)

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 handles GIMP 3 differences and known issues.
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.

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

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]

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install GIMP Studio MCP?

Does GIMP Studio MCP need an API key?

What transport does GIMP Studio MCP use?

When was GIMP Studio MCP last checked?

Documentation

GIMP Studio MCP

Why this server

The design rules (every tool follows these)

Architecture (hybrid, day one)

Capability areas (119 tools)

Requirements

Installation

1. Install the server

2. Install the GIMP-side bridge

3. Register with your MCP client

Quick start

General editing

DTF (direct-to-film) — the headline workflow

Security model

Environment variables

Troubleshooting

License