GIMP MCP Pro

Production-grade Model Context Protocol server for GIMP 3.0+

67 typed tools • reliable communication • AI-friendly workflows

GIMP MCP Pro lets AI assistants (Claude, etc.) control GIMP through well-structured, typed MCP tools — creating images, managing layers, drawing shapes, applying filters, adjusting colors, and more.

Features

• 67 typed MCP tools across 11 modules — image management, layers, selections, drawing, text, transforms, colors, filters, inspection, history, PDB access
• Reliable communication — length-prefixed socket framing (no more JSON boundary guessing)
• Persistent connections — one TCP connection, kept alive, with automatic reconnection
• GIMP 3.0.8 compatible — tested against current GIMP release using stable APIs (DrawableFilter, PDB procedures)
• Undo groups — multi-step AI workflows as a single undo step
• Pydantic validation — inputs validated before reaching GIMP
• AI guidance prompts — best practices and iterative workflow documentation
• Visual verification — get_image_bitmap lets AI see what it's drawing
• PDB discovery — search GIMP's thousands of procedures
• Escape hatch — execute_python for anything without a dedicated tool

Architecture

AI Assistant  ←→  MCP Server (gimp-mcp-pro)  ←→  GIMP Plugin
   (Claude)         stdio/SSE                      TCP socket
                    Typed tools                    PyGObject
                    Pydantic models                Native handlers

Two processes: the MCP server runs outside GIMP and communicates with a plugin running inside GIMP's Python process via TCP with length-prefixed framing.

Quick Start

1. Install the MCP server

pip install gimp-mcp-pro

Or install from source:

git clone https://github.com/yourname/gimp-mcp-pro.git
cd gimp-mcp-pro
pip install -e .

2. Install the GIMP plugin

The setup script handles this automatically:

./setup.sh

Or manually copy the plugin:

# Linux
PLUG_DIR="$HOME/.config/GIMP/3.0/plug-ins/gimp-mcp-pro"
mkdir -p "$PLUG_DIR"
cp gimp_plugin/gimp_mcp_plugin.py "$PLUG_DIR/gimp-mcp-pro"
chmod +x "$PLUG_DIR/gimp-mcp-pro"

# macOS
PLUG_DIR="$HOME/Library/Application Support/GIMP/3.0/plug-ins/gimp-mcp-pro"
mkdir -p "$PLUG_DIR"
cp gimp_plugin/gimp_mcp_plugin.py "$PLUG_DIR/gimp-mcp-pro"
chmod +x "$PLUG_DIR/gimp-mcp-pro"

3. Start the plugin in GIMP

Open GIMP → Tools → Start MCP Pro Server

You should see "MCP Pro: Listening on localhost:9877" in the GIMP console.

4. Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gimp": {
      "command": "gimp-mcp-pro"
    }
  }
}

Restart Claude Desktop.

5. Start editing!

Ask Claude: "Create an 800x600 image with a red circle in the center and the text 'Hello World' below it"

Tool Reference

Image Management (6 tools)

Layer Operations (9 tools)

Drawing (9 tools)

Selections (8 tools)

Transforms (11 tools)

Color Adjustments (13 tools)

Filters & Effects (8 tools)

Inspection (4 tools)

History (3 tools)

Advanced (2 tools)

Known Limitations

• Undo/Redo: GIMP 3.0's plugin API does not expose programmatic undo/redo. Use Ctrl+Z/Ctrl+Y in GIMP directly. Undo groups work for grouping AI operations.
• Drop Shadow: Uses Script-Fu internally; may cause connection issues on some setups.
• Font Names: GIMP 3.0 uses names like Sans-serif, Serif, Monospace. The add_text tool maps common aliases automatically.

Environment Variables

Technical Notes

Filter Implementation

All filters use Gimp.DrawableFilter which safely wraps GEGL operations within GIMP's plugin context. Direct GEGL graph construction (Gegl.Node()) crashes in GIMP 3.0 plugin context — this is a known limitation that GIMP MCP Pro works around.

Color Handling

Colors are accepted as names ("red"), hex ("#FF0000"), or CSS rgb ("rgb(255,0,0)") across all tools. Internally, colors use Gegl.Color objects with the GIMP 3.0 API.

Connection Protocol

The MCP server communicates with the GIMP plugin over TCP using 4-byte big-endian length-prefixed JSON messages. This eliminates the fragile JSON boundary detection used by earlier implementations.

Development

git clone https://github.com/yourname/gimp-mcp-pro.git
cd gimp-mcp-pro
pip install -e ".[dev]"
pytest

Credits

Built on insights from:

• maorcc/gimp-mcp — proven GIMP plugin architecture, AI guidance prompts
• slliws/gimp-mcp-server — typed tool module structure
• libreearth/gimp-mcp — original proof-of-concept

License

MIT