gimp-mcp

GIMP MCP Server

Professional image editing through GIMP 3 — controlled by AI agents via the Model Context Protocol. 18 portmanteau tools consolidate GIMP's ~1000 PDB procedures into clean, discoverable operations.

Quick Start

git clone https://github.com/sandraschi/gimp-mcp
cd gimp-mcp
just

This opens an interactive dashboard showing all available commands. Run just bootstrap to install dependencies, then just serve or just dev to start.

Manual Setup

If you don't have just installed:

1. Install GIMP 3.2+ (standalone, not Windows Store) from gimp.org
2. Run uv sync to install Python dependencies
3. Launch GIMP with the bridge plugin: .\start.ps1 -RestartGimp
4. Open http://localhost:10772

Table of Contents

Document	What's inside
📦 Installation	Prerequisites, MCPB install, GIMP 3, uv sync, Agent Lab pipelines
Competitive Analysis	GIMP MCP landscape and fleet differentiation
Roadmap	Agent Lab phases (bridge, vision, fleet handoff)
Fleet Pipeline	blender -> gimp -> unity texture handoff
Monitoring	Prometheus metrics and Loki JSON logs
Sim Art Pipeline	Gazebo icons, atlases, VRChat handoff
🏗️ Architecture	4-layer design, portmanteau pattern, tool registration flow, Live vs Headless, ports
🖼️ GIMP Integration	Live Bridge mechanics, PDB proxy, GIMP 3 Python-Fu, known limitations, troubleshooting
🧩 GIMP Plugins	Bridge plugin architecture, installation, lifecycle, protocol, extending, directory locations
⚙️ CLI & API	CLI batch mode, PDB proxy ref, REST API, webapp pages, all 21 justfile recipes

Tools

Tool	Ops	Description
gimp_file	6	load, save, convert, info, validate, list_formats
gimp_transform	7	resize, crop, rotate, flip, scale, perspective, autocrop
gimp_color	12	brightness, contrast, levels, curves, HSL, balance, auto, invert, threshold, posterize, desaturate, colorize
gimp_filter	8	blur, sharpen, noise, edge_detect, artistic, enhance, distort, light_shadow
gimp_layer	8	create, duplicate, merge, flatten, opacity, blend, reorder, info
gimp_analysis	8	quality, statistics, histogram, compare, detect_issues, report, color_profile, metadata
gimp_batch	6	resize, convert, process, watermark, rename, optimize
gimp_system	8	status, help, diagnostics, cache, config, performance, tools, version
gimp_pdb	∞	Universal PDB proxy — call any of ~1000+ GIMP procedures by name
gimp_workspace	10	list images, undo/redo, undo groups, metadata, resolution
gimp_channel	8	create, delete, list, set color/opacity, duplicate channels
gimp_animation	5	list frames, set delay, optimize/export GIF
gimp_paths	8	create, delete, stroke, import/export SVG, vector paths
gimp_parasites	9	XCF metadata: list, attach, detach parasites on images/drawables
gimp_gmic	4	G'MIC filter integration — 500+ filters via plug-in-gmic
gimp_gegl	2	GEGL non-destructive editing operations
gimp_color_management	7	ICC profiles, assignment, conversion, soft proofing
gimp_snapshot	1+	get_state_snapshot — live base64 PNG of current canvas (region crop, max_size). Enables AI vision loop: edit → snapshot → assess → refine. Requires optional GIMP bridge plugin.

Optional: GIMP Bridge Plugin

For live interaction with a running GIMP (real-time snapshots, undo/redo, interactive editing), install the bridge plugin:

1. Copy plugins/gimp_mcp_bridge/gimp_mcp_bridge.py to GIMP's plug-ins directory
   • Windows: %APPDATA%\GIMP\3.2\plug-ins\gimp_mcp_bridge\
   • macOS: ~/Library/Application Support/GIMP/3.2/plug-ins/gimp_mcp_bridge/
   • Linux: ~/.config/GIMP/3.2/plug-ins/gimp_mcp_bridge/
2. Restart GIMP
3. Go to Filters > Development > MCP > Start MCP Bridge
4. Server auto-detects the bridge on port 10824

Without the plugin, all tools fall back to headless CLI mode (gimp-console-3.exe).

Example: Resize an Image

User: "Resize this photo to 1920x1080"

Agent calls: gimp_transform(operation="resize",
  input_path="C:/photos/sunset.jpg",
  output_path="C:/photos/sunset_1920.jpg",
  width=1920, height=1080)

Response: {"success": true, "message": "Resized sunset.jpg from
  4000x2250 to 1920x1080 (lanczos, 95% quality)", ...}

Behind the scenes — the tool detects whether GIMP is running (Live Bridge via TCP :10824) or not (Headless CLI via gimp-console-3.exe), and routes the operation accordingly.

Webapp

The webapp (http://localhost:10772) is a full SOTA React/Tailwind/Zustand dashboard with:

Page	Features
LLM Chat	localStorage-persistent conversation history (100 msg cap), 5 personalities (GIMP Expert, Research Assistant, Expert Reviewer, Quick Summarizer, Custom), skills-as-preprompt (fetched from /api/skills on mount), 8 clickable example prompts, Export (.txt download), Clear, voice input (STT via Web Speech API), TTS read-aloud per message, editable model name, provider status indicator (green/red dot), data-testid attributes on all controls
Dashboard	System health, bridge status, version, KPIs
Apps Hub	Dynamic fleet discovery
Tools Explorer	Portmanteau drill-down with docstrings/schemas
Skills	Markdown-rendered skill browser
Agent Tools	Bridge, Vision, Validation, Capture Gallery tabs
Settings	AI provider API keys, local LLM provider/model
API Docs	Swagger UI + ReDoc via iframe

Claude Desktop

Claude-only one-liner (Windows, installs the released .mcpb bundle):

irm https://github.com/sandraschi/gimp-mcp/releases/latest/download/install.ps1 | iex

Every other client (manual config, local clone):

{
  "mcpServers": {
    "gimp-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sandraschi/gimp-mcp", "gimp-mcp"]
    }
  }
}

Developer fallback (local checkout, stdio):

{
  "mcpServers": {
    "gimp-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "gimp_mcp.main"],
      "cwd": "D:\\Dev\\repos\\gimp-mcp"
    }
  }
}

Stdio transport is the default (uv run python -m gimp_mcp.main); the HTTP backend (http://127.0.0.1:10773) serves the webapp and Tauri wrapper.

License

MIT — see LICENSE for details.

---

Built with FastMCP 3.2 by sandraschi