gimp-mcp

gimp-mcp is an MCP server so AI agents can drive GIMP-style image operations: open/create images, resize, crop, flip, rotate, blur, desaturate, text overlay, export, and batch resize.

Mode	Backend	When
mock (default)	Pillow	CI, offline, no GIMP install
live	gimp-console batch + Pillow assist	Machine with GIMP 2.10 / 3.x

Product: mergeos-bounties/gimp-mcp · Funded: prj_0525

---

Install (one command)

Grok — recommended

pip install "git+https://github.com/mergeos-bounties/gimp-mcp.git" && grok plugin install mergeos-bounties/gimp-mcp --trust

This installs the Python CLI (gimp-mcp) and the Grok plugin (skill + MCP server from .mcp.json).

Check:

gimp-mcp version
gimp-mcp doctor
gimp-mcp demo
grok plugin list
grok mcp list

Local clone:

git clone https://github.com/mergeos-bounties/gimp-mcp.git
cd gimp-mcp
pip install -e ".[dev]"
grok plugin install . --trust

Other agents (stdio MCP)

After pip install "git+https://github.com/mergeos-bounties/gimp-mcp.git", point any MCP host at:

Field	Value
command	gimp-mcp
args	["serve"]
env	GIMP_MCP_MODE=mock

Claude Desktop — merge examples/claude_desktop_config.json into Claude MCP config.

Cursor — merge examples/cursor_mcp.json.

Grok config.toml (manual, without plugin):

[mcp_servers.gimp_mcp]
command = "gimp-mcp"
args = ["serve"]
env = { GIMP_MCP_MODE = "mock" }
enabled = true

One-liner via Grok CLI:

pip install "git+https://github.com/mergeos-bounties/gimp-mcp.git"
grok mcp add gimp-mcp -- gimp-mcp serve

Supported AI agents / hosts

Host	Support	Install
Grok (CLI / TUI / Build)	Yes	grok plugin install mergeos-bounties/gimp-mcp --trust then pip install "git+https://github.com/mergeos-bounties/gimp-mcp.git"
Claude Desktop	Yes	Copy examples/claude_desktop_config.json into Claude MCP settings
Cursor	Yes	Merge examples/cursor_mcp.json into Cursor MCP config
Claude Code	Yes	stdio MCP: same command/args as Claude Desktop / Grok
VS Code (MCP / Continue / Cline)	Yes	Generic stdio server config pointing at gimp-mcp serve
Windsurf / Cascade	Yes	stdio MCP entry with gimp-mcp + serve
Codex CLI	Yes (stdio)	Register MCP server command gimp-mcp serve in Codex MCP settings
ChatGPT Desktop	Partial	Only if host supports custom MCP stdio servers
Gemini CLI	Partial	Only if MCP stdio plugins are enabled

All packages speak MCP over stdio (gimp-mcp serve). Default mode is mock (offline, no simulator/terminal/GIMP required).

---

Highlights

Capability	Description
MCP tools	gimp_doctor, gimp_open, gimp_resize, gimp_export, …
CLI	gimp-mcp demo, doctor, live-smoke, serve, call
Offline demo	Always works with Pillow mock
Live GIMP 3	python-fu-eval + --quit (~2s scale on Windows)
Live GIMP 2	Script-Fu batch
Grok plugin	skills/gimp-mcp + .mcp.json + .grok-plugin/plugin.json

---

Quick start (developers)

cd mcp\GIMP-mcp
pip install -e ".[dev]"
gimp-mcp version
gimp-mcp doctor
gimp-mcp demo
pytest -q

Live GIMP (optional)

# Install GIMP 3.x, then:
$env:GIMP_MCP_MODE = "live"
# optional override:
# $env:GIMP_MCP_BIN = "$env:LOCALAPPDATA\Programs\GIMP 3\bin\gimp-console.exe"
gimp-mcp doctor
gimp-mcp live-smoke

MCP host config

Plugin ships .mcp.json. Manual examples: examples/claude_desktop_config.json, examples/cursor_mcp.json.

{
  "mcpServers": {
    "gimp-mcp": {
      "command": "gimp-mcp",
      "args": ["serve"],
      "env": { "GIMP_MCP_MODE": "live" }
    }
  }
}

---

CLI / tools

Command	Purpose
gimp-mcp version	Package + detected console
gimp-mcp doctor	Backend health
gimp-mcp demo	Mock end-to-end smoke
gimp-mcp live-smoke	Live console smoke (skips if missing)
gimp-mcp tools list	MCP tool names
gimp-mcp call …	One-shot tool (key=value)
gimp-mcp process <image>	Full real-photo pipeline → multiple exports
gimp-mcp serve	Stdio MCP server

Real photos

$env:GIMP_MCP_MODE = "live"
gimp-mcp process "C:\path\to\photo.jpg" --out-dir ".\examples\real-run" --watermark "MergeOS"

Writes *_processed.png, *_gray.png, *_crop_flip_*.png, and batch_thumbs/ (GIMP 3 scale via python-fu-eval).

MCP tools: gimp_mode, gimp_doctor, gimp_seed_demo, gimp_list_images, gimp_close, gimp_new_image, gimp_open, gimp_info, gimp_resize, gimp_thumbnail, gimp_crop, gimp_flip, gimp_rotate, gimp_blur, gimp_sharpen, gimp_desaturate, gimp_invert, gimp_brightness, gimp_contrast, gimp_auto_orient, gimp_text_overlay, gimp_pipeline, gimp_export, gimp_batch_resize.

Env:

Variable	Meaning
GIMP_MCP_MODE	mock (default) or live
GIMP_MCP_BIN	Path to gimp-console
GIMP_MCP_WORKSPACE	Working directory for temp images
GIMP_MCP_TIMEOUT	Batch timeout seconds

---

Development

pip install -e ".[dev]"
ruff check src tests
pytest -q

Plugin layout:

.grok-plugin/plugin.json   # Grok plugin manifest
.mcp.json                  # MCP stdio server for Grok
skills/gimp-mcp/           # Skill (auto-loaded after plugin install)
.grok/skills/gimp-mcp/     # Same skill for in-repo discovery

---

MergeOS bounties

Follow mergeos-bounties + star mergeos and mergeos-contracts. Claim issues → PR to master → 25–200 MRG.

See docs/BOUNTY.md.

---

License

MIT — see LICENSE.

Live test note (maintainer)

Verified on Windows with GIMP 3.2.4 at
%LOCALAPPDATA%\Programs\GIMP 3\bin\gimp-console.exe

• Live resize uses python-fu-eval + --quit (not Script-Fu hang)
• gimp-mcp live-smoke completes in a few seconds
• Filters may still use Pillow assist by design