# GimpMCP

An MCP server that lets an LLM (Claude Code, Claude Desktop, etc.) drive a **running GIMP 3.0**
instance — images, layers, selections, gradients, text, transforms, filters, or arbitrary
Script-Fu code.

If GIMP's window is open, you watch the edits happen live.

## Setup

1. Install [GIMP 3.0](https://www.gimp.org/downloads/).
2. Install this server:
   ```powershell
   python -m venv .venv
   .venv\Scripts\pip install -e .
   ```
3. Register it with your MCP client (`claude mcp add`, or `.mcp.json`):
   ```json
   {
     "mcpServers": {
       "gimp": {
         "command": "C:\\path\\to\\GimpMCP\\.venv\\Scripts\\python.exe",
         "args": ["-m", "gimp_mcp.server"]
       }
     }
   }
   ```

## Turn on live mode

In GIMP: **Filters ▸ Development ▸ Script-Fu ▸ Script-Fu Server** → keep `127.0.0.1` / port
`10008` → **Start**.

That's it. Now ask Claude things like:

> open C:\photos\cat.png in GIMP, resize it to 800x600, and export it as cat_small.jpg

and you'll see each step land in the GIMP window.

## What it can do

35 tools, grouped:

- **Images** — open, create, export, resize, crop, rotate, flip, flatten, inspect, close
- **Layers** — list, add, duplicate, move, fill, opacity, visibility
- **Selections** — rectangle, ellipse, clear
- **Paint & type** — gradient fill, text layers, font listing
- **Adjust & filter** — blur, sharpen, brightness/contrast, desaturate, invert
- **Escape hatches** — `apply_gegl_filter` (any of GIMP's ~400 GEGL filters) and
  `run_script_fu` (arbitrary Scheme against the full ~2,000-procedure PDB), with
  `search_gimp_api` to discover what exists

Run `gimp_status` any time to check what it's connected to.

## Troubleshooting

| Problem | Fix |
|---|---|
| Tools refuse with a "start the server" hint | GIMP is open but the Script-Fu server isn't running — see *Turn on live mode* above |
| "Can't find GIMP" | Set `GIMP_EXECUTABLE` to your full `gimp-console-3.0.exe` path |
| Edits happen but you can't see them | You're on a headless instance; open GIMP and start its Script-Fu server |
| A procedure errors out | You're likely hitting a GIMP 2.x name that no longer exists — see the notes below |

Verified on **Windows + GIMP 3.0.8**. macOS/Linux detection is implemented but untested.
GIMP 2.10 is not supported.

## Digging deeper

[**NOTES.md**](NOTES.md) — the GIMP 3.0 PDB changes that trip everyone up (renamed procedures,
the removed `plug-in-*` filter family, the text-layer footgun), the socket protocol, and how to
find procedures GIMP doesn't document.

## License

MIT — see [LICENSE](LICENSE).