Gimp Mcp
GIMP MCP server
Full demo (with audio): https://github.com/gimp-mcp/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
- 79 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 |
| 🎨 79 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 (59/59 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)
- uv — Python package manager (install uv);
uvxdownloads the MCP server and a suitable Python (3.11+) on first use - MCP-compatible AI client — Claude Desktop, Claude Code, Gemini CLI, PydanticAI, etc.
Quick Start
The MCP server and the GIMP plugin ship together as the gimp-mcp-plugin package on PyPI. No clone needed.
1. Install the GIMP Plugin
Launch GIMP once (so its config folder exists), close it, then run:
uvx gimp-mcp-plugin@latest install-plugin
This copies the plugin into the newest GIMP 3.x config folder it finds (Linux standard, Snap and Flatpak locations, macOS, Windows) and makes it executable. Restart GIMP afterward.
--dry-runshows where it would install without writing anything.--gimp-dir DIRinstalls into a specific GIMP config folder, e.g.--gimp-dir ~/.config/GIMP/3.2.
If you have more than one GIMP 3 installation (e.g. a system GIMP and a Flatpak), the newest folder found may not be the one your GIMP uses. Check the folder shown in GIMP's Edit → Preferences → Folders → Plug-ins and pass the folder that contains plug-ins with --gimp-dir.
From the project's README.