GIMP MCP

Demo

Full demo (with audio): https://github.com/maorcc/gimp-mcp/raw/main/docs/demo.mp4

AI agent using GIMP MCP to remove a background, edit a character's expression, and verify results — all through natural language via Claude

---

Overview

GIMP MCP bridges GIMP's professional image editing capabilities with AI assistants through the Model Context Protocol. It lets you edit images by describing what you want — and gives the AI a live visual feedback channel to verify each change before moving on.

What makes it different from other GIMP integrations:

• The AI can see the image at any point in the workflow without saving to disk (get_state_snapshot)
• Supports fully autonomous multi-step pipelines: open → edit → verify → refine → export
• 56 dedicated tool commands covering every major GIMP operation
• Fully compatible with GIMP 3.2.x (all breaking API changes resolved)

Key Features

👁️ Live Visual Feedback	get_state_snapshot returns a PNG preview mid-workflow so the AI verifies each step
🎨 56 GIMP Tools	Adjustments, transforms, selections, layers, drawing, text, filters — all via MCP
🔧 GIMP 3.2 Compatible	All GIMP 3.2 API breaks fixed and tested (56/56 passing)
🔁 Iterative Workflows	AI loops until a goal is met — e.g. keeps removing BG until no pixels remain
🖼️ Region Snapshots	Zoom into any area for detail verification (face, mouth, corner, etc.)
🔌 Universal MCP	Works with Claude Desktop, Claude Code, Gemini CLI, PydanticAI, and more

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.

Which directory? GIMP names its per-user folder after its major.minor version (3.0, 3.2, 3.4, …) and creates a fresh one on each minor upgrade, so the folder moves when you upgrade GIMP (e.g. 3.0 → 3.2). The snippet below auto-selects the newest one, so it keeps working across upgrades. To check the path manually, open GIMP and look at Edit → Preferences → Folders → Plug-ins.

Launch GIMP at least once before running this, so its config folder exists.