GIMP Studio MCP

Overview

GIMP Studio MCP lets an MCP-compatible AI agent drive GIMP 3.x with 117 structured, parameter-validated tools instead of hand-written GIMP Python. Every tool returns a structured result so output is never lost, even on error, and a GIMP-3 compatibility layer absorbs the known 3.x quirks. The server attaches to a running GIMP or spawns a headless one automatically — the same tools work identically in both modes. It was built for a working print shop's DTF (direct-to-film) pipeline, so DPI awareness and DTF output are first-class.

Features

• 117 tools across 13 groups for full image control
• Structured returns - every tool reports ok/result/stdout/warnings/error, so output is never lost
• Live or headless - one bridge auto-attaches to a running GIMP or spawns a headless GIMP automatically
• Vision-first - get_bitmap returns a viewable preview the agent can actually see, for self-verification
• Print / DTF tooling - white underbase, edge choke/spread, garment-aware background knockout, halftone separation, gang-sheet and DTF PNG export
• Safety by default - checkpoint/restore, undo/redo, and undo groups around destructive ops
• GIMP-3 compatibility layer - centralizes 3.x gotchas so they don't need relearning per session

Requirements

• GIMP 3.x (verified on 3.0.4 and 3.2.4; GIMP 2.x is not supported)
• Python 3.10+ (for the MCP server)
• An MCP-compatible AI client (Claude Desktop, Claude Code, etc.)
• The GIMP-side bridge, installed with gimp-mcp install-plugin

Installation

Step 1: Install the Server

pipx 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

Install the bridge into GIMP's plug-ins directory, then verify the setup:

gimp-mcp install-plugin
gimp-mcp doctor

Restart GIMP (or it loads on next launch). The bridge auto-starts as a persistent extension. gimp-mcp doctor checks the install, locates the GIMP executable, and round-trips the bridge; add --headless to also spawn and verify a headless GIMP.

Step 3: Register With Your AI Client

Add the server to your MCP client's configuration:

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

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

Available Tools (117)

Tools are self-describing through your MCP client; describe_op and the list_* tools enumerate ops and resources at runtime.

Usage Examples

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

Knock out the black shirt color behind this artwork

Add a white underbase choked 2px so it doesn't peek

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 more) and it picks the right removal technique for that garment. Run list_shirt_presets to see the catalog.

FAQ