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)