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.

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:

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

Related MCP server: MCP OpenAI Image Generation Server

Supported AI agents / hosts

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

Highlights

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

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:

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