What Can It Do?

Background Removal with Iterative Verification

The AI removes the background, takes a snapshot to inspect the result, detects remaining pixels, and loops until the image is clean:

"Remove the background from this image and keep looping until only the character remains"

Expression Editing

"Make the character smile — paint a smile arc with teeth over her mouth"

Complex Multi-Step Pipelines

"Open navi_portrait.png, remove the background, verify it's clean,
 then make her smile and export the final result as a PNG"

Color & Tone Work

"Boost the contrast, shift the hue 15 degrees warmer, then show me a before/after zoom of the face"

Text & Compositing

"Add a bold title at the top in white with a subtle drop shadow, then export for web"

Prerequisites

• GIMP 3.2+ — tested on GIMP 3.2.2 (Windows, macOS, Linux)
• Python 3.8+ — for the MCP server
• uv — Python package manager (pip install uv)
• MCP-compatible AI client — Claude Desktop, Claude Code, Gemini CLI, PydanticAI, etc.

Quick Start

1. Install Dependencies

git clone https://github.com/maorcc/gimp-mcp.git
cd gimp-mcp
uv sync

2. Install the GIMP Plugin

Copy gimp-mcp-plugin.py to GIMP's plug-ins directory and restart GIMP.

Linux (standard):

mkdir -p ~/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin
cp gimp-mcp-plugin.py ~/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin/
chmod +x ~/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py

Linux (Snap):

mkdir -p ~/snap/gimp/current/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin
cp gimp-mcp-plugin.py ~/snap/gimp/current/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin/
chmod +x ~/snap/gimp/current/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py

macOS:

mkdir -p ~/Library/Application\ Support/GIMP/3.0/plug-ins/gimp-mcp-plugin
cp gimp-mcp-plugin.py ~/Library/Application\ Support/GIMP/3.0/plug-ins/gimp-mcp-plugin/
chmod +x ~/Library/Application\ Support/GIMP/3.0/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py

Windows:

%APPDATA%\GIMP\3.2\plug-ins\gimp-mcp-plugin\gimp-mcp-plugin.py

No chmod needed on Windows. Just copy and restart GIMP.

For all platforms: GIMP Plugin Installation Guide

3. Start the MCP Server in GIMP

1. Open any image in GIMP
2. Go to Tools > Start MCP Server
3. Server starts on localhost:9877

4. Configure Your MCP Client

Claude Desktop

~/.config/Claude/claude_desktop_config.json (Linux/macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gimp": {
      "command": "uv",
      "args": ["run", "--directory", "/full/path/to/gimp-mcp", "gimp_mcp_server.py"]
    }
  }
}

Claude Code

cd /path/to/gimp-mcp
claude  # .mcp.json is auto-detected

Or manually:

claude mcp add gimp-mcp -- uv run --directory /full/path/to/gimp-mcp gimp_mcp_server.py

Gemini CLI

~/.config/gemini/.gemini_config.json:

{
  "mcpServers": {
    "gimp": {
      "command": "uv",
      "args": ["run", "--directory", "/full/path/to/gimp-mcp", "gimp_mcp_server.py"]
    }
  }
}

PydanticAI

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

server = MCPServerStdio('uv', args=['run', '--directory', '/path/to/gimp-mcp', 'gimp_mcp_server.py'])
agent = Agent('openai:gpt-4o', mcp_servers=[server])

Available MCP Tools

👁️ Visual Feedback

get_state_snapshot(image_index, max_size, region, label)

Returns a live PNG of the current image state — the AI's primary feedback mechanism. Call this between any edits to verify the result without saving to disk.

# Full image snapshot
snapshot = get_state_snapshot(max_size=512)

# Zoom into a face region for detail inspection
snapshot = get_state_snapshot(
    region={"x": 140, "y": 80, "width": 240, "height": 300},
    max_size=512,
    label="face-check"
)

This enables iterative agentic workflows: edit → snapshot → assess → refine → repeat.

get_image_bitmap(image_index, max_width, max_height, region)

Lower-level bitmap fetch with region extraction and scaling. Returns base64-encoded PNG.

🎨 Adjustments

| Tool | Description | |---|---| | adjust_brightness_contrast | Brightness and contrast | | adjust_curves | Curves by channel (RGB/R/G/B/A) | | adjust_hue_saturation | Hue, saturation, lightness | | adjust_color_balance | Shadows/midtones/highlights color balance | | auto_levels | Auto-stretch levels | | desaturate | Convert to grayscale (keep RGB mode) | | invert_colors | Invert all channels | | sharpen | Unsharp mask sharpening | | blur | Gaussian blur | | denoise | Noise reduction |

🔄 Transforms

| Tool | Description | |---|---| | scale_image | Scale to exact dimensions | | scale_to_fit | Scale within bounding box (aspect-safe) | | crop_to_rect | Crop to rectangle | | rotate_image | Rotate 90/180/270 or arbitrary angle | | flip_image | Flip horizontal or vertical | | resize_canvas | Resize canvas without scaling content |

✂️ Selections

| Tool | Description | |---|---| | select_rectangle | Rectangular marquee | | select_ellipse | Elliptical marquee | | select_by_color | Select by color (global) | | select_all / select_none | Select all / deselect | | invert_selection | Invert selection | | modify_selection | Grow, shrink, feather, or border |

🗂️ Layers

| Tool | Description | |---|---| | create_layer | New empty layer | | duplicate_layer | Duplicate active layer | | delete_layer | Delete named layer | | rename_layer | Rename layer | | set_layer_properties | Opacity, blend mode, visibility | | reorder_layer | Move layer in stack | | merge_visible_layers | Flatten visible to one layer | | flatten_image | Flatten all layers | | list_layers | List all layers with properties |

🖌️ Drawing & Fill

| Tool | Description | |---|---| | fill_layer | Fill entire layer with color | | fill_selection | Fill selection (foreground/background/transparent) | | fill_rectangle | Fill a rectangle region | | fill_ellipse | Fill an ellipse region | | draw_line | Draw a line (pencil or paintbrush) | | draw_rectangle | Draw a rectangle outline | | draw_ellipse | Draw an ellipse outline | | gradient_fill | Apply linear or radial gradient | | set_colors | Set foreground/background colors |

🔤 Text

| Tool | Description | |---|---| | add_text | Add a text layer | | edit_text | Edit existing text layer | | list_fonts | List available fonts |

✨ Filters & Effects

| Tool | Description | |---|---| | apply_gaussian_blur | Gaussian blur filter | | apply_pixelate | Pixelate/mosaic effect | | apply_emboss | Emboss effect | | apply_vignette | Vignette darkening | | apply_noise | Add noise/grain | | apply_drop_shadow | Drop shadow effect |

📁 File Operations

| Tool | Description | |---|---| | open_image | Open image file | | export_image | Export to PNG, JPEG, BMP, TIFF | | new_canvas | Create blank canvas | | close_image | Close image | | list_images | List open images |

🔍 Info & Context

| Tool | Description | |---|---| | get_image_metadata | Image size, mode, layers, filename | | get_gimp_info | GIMP version, platform, capabilities | | get_context_state | Current colors, brush, opacity, mode | | get_pixel_color | Color value at a specific pixel | | get_histogram | Histogram data for a channel | | get_selection_bounds | Current selection bounds |

AI Agent Feedback Loop

The get_state_snapshot tool enables