{"id":"43aacf3a-eb8e-46b1-99db-1a9cd97f4719","slug":"ryancurrah-mcp-gimp","kind":"mcp","name":"mcp-gimp","summary":"Drive [GIMP 3](https://www.gimp.org/) from an MCP client. 80+ tools covering canvases, layers, selections, drawing, text, colour adjustments, GEGL filters and export, plus a typed escape hatch onto GI","owner":"ryancurrah","repoUrl":"https://github.com/ryancurrah/mcp-gimp","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-09-20T23:58:33.000Z","addedAt":"2026-10-21T09:44:55.578Z","logoUrl":"https://avatars.githubusercontent.com/u/6209771?u=9d81ec835f9d3b4bc096422950567b213cea1098&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["databases"],"tags":["gimp","gimp-plugin"],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T07:33:11.869Z","sample":false,"url":"https://conduits.dev/tools/ryancurrah-mcp-gimp","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# mcp-gimp\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nDrive [GIMP 3](https://www.gimp.org/) from an MCP client. 92 tools covering\ncanvases, layers, selections, drawing, text, colour adjustments, GEGL filters\nand export, plus a typed escape hatch onto GIMP's full procedural database.\n\n## Quick start\n\n**1. Install the MCP server and the GIMP plug-in.** On macOS:\n\n```bash\nbrew tap ryancurrah/tap\nbrew install --cask mcp-gimp gimp-mcp-plugin\n```\n\nOn Linux and Windows, see [Installing elsewhere](#installing-elsewhere).\n\n**2. Start the plug-in inside GIMP.** Restart GIMP, then, in GIMP's own\nmenu bar, click **Tools > MCP > Start MCP Server**. A dialog offers the\naddress to bind — the defaults are fine — and GIMP confirms\n`MCP server listening on 127.0.0.1:9877`. Leave GIMP running.\n\n<img src=\"https://raw.githubusercontent.com/ryancurrah/mcp-gimp/main/docs/images/tools-menu.png\" alt=\"GIMP's Tools menu with the MCP submenu open, showing Start MCP Server and Stop MCP Server\" width=\"560\">\n<img src=\"https://raw.githubusercontent.com/ryancurrah/mcp-gimp/main/docs/images/start-options.png\" alt=\"The Start MCP Server dialog: Host 127.0.0.1, Port 9877, with Cancel and Start buttons\" width=\"444\">\n\n**3. Register the server with your MCP client.** In Claude Code:\n\n```bash\nclaude mcp add gimp --scope user -- mcp-gimp\n```\n\n`--scope user` registers it once for every project. Drop it to add the server\nto the current project only.\n\nAny other client takes the same thing as config:\n\n```json\n{\n  \"mcpServers\": {\n    \"gimp\": {\n      \"command\": \"mcp-gimp\"\n    }\n  }\n}\n```\n\n**4. Confirm the client can reach GIMP.** Ask it to run `check_server`. If\nthat returns `connected: true`, you're done — try:\n\n```\nnew_canvas(width=1024, height=768, fill=\"white\")\nfill_ellipse(x=100, y=100, width=200, height=150, color=\"#3366cc\")\nexport_image(file_path=\"/abs/path/out.png\")\n```\n\n## Why there are two pieces\n\n```\nMCP client  ──stdio──>  mcp-gimp  ──TCP 9877──>  gimp-mcp-plugin  ──libgimp──>  GIMP\n            (JSON-RPC)  (server)   (JSON)        (plug-in, in GIMP)\n```\n\nYour MCP client launches the **server**; GIMP loads the **plug-in**. Different\nthings start each one, so they ship separately and you install both. The\nplug-in is native code linked against libgimp — there is no scripting runtime\nin the loop.\n\n## Troubleshooting\n\n**`check_server` says `connected: false`.** GIMP isn't running the plug-in.\nStart GIMP and click **Tools > MCP > Start MCP Server** in its menu bar.\n\n**Nothing happened when I clicked Start MCP Server.** It reports through\nGIMP's own message handling, which **Edit > Preferences > Interface > Message\nHandling** may have pointed at the error console rather than a dialog. Either\nway, `check_server` is the real test.\n\n**It says the address is already in use.** The server is already running —\nthere is one per GIMP, not one per click. Use **Tools > MCP > Stop MCP\nServer** first, or just leave the running one alone.\n\n**There's no MCP submenu under GIMP's Tools menu.** GIMP didn't load the\nplug-in:\n\n- Restart GIMP — plug-ins are only scanned at startup.\n- If you upgraded GIMP since installing, its plug-ins directory moved. On\n  Homebrew, `brew reinstall --cask gimp-mcp-plugin`; otherwise install it\n  again in the new directory.\n- Check you used the directory shown in\n  **Edit > Preferences > Folders > Plug-ins**.\n- This plug-in needs GIMP 3. It will not load in GIMP 2.10.\n\nMore detail, including the macOS Gatekeeper step, is in\n[plugin/INSTALL.md](plugin/INSTALL.md).\n\n## Installing elsewhere\n\n### The plug-in\n\nSet `ARCHIVE` to your platform, and `DEST` to the path GIMP shows under\n**Edit > Preferences > Folders > Plug-ins**:\n\n| Platform | `ARCHIVE` |\n| --- | --- |\n| Linux x86_64 | `gimp-mcp-plugin_Linux_x86_64.tar.gz` |\n| Linux arm64 | `gimp-mcp-plugin_Linux_arm64.tar.gz` |\n| macOS Intel | `gimp-mcp-plugin_Darwin_x86_64.tar.gz` |\n| macOS Apple Silicon | `gimp-mcp-plugin_Darwin_arm64.tar.gz` |\n| Windows x86_64 | `gimp-mcp-plugin_Windows_x86_64.tar.gz` |\n\n```bash\nARCHIVE=gimp-mcp-plugin_Linux_x86_64.tar.gz\nDEST=~/.config/GIMP/3.0/plug-ins\n\nmkdir -p \"$DEST\"\ncurl -fL \"https://github.com/ryancurrah/mcp-gimp/releases/latest/download/$ARCHIVE\" \\\n  | tar -xzf - -C \"$DEST\"\n```\n\nOn Windows, in PowerShell:\n\n```powershell\n$archive = \"gimp-mcp-plugin_Windows_x86_64.tar.gz\"\n$dest = \"$env:APPDATA\\GIMP\\3.0\\plug-ins\"\n\nNew-Item -ItemType Directory -Force -Path $dest | Out-Null\ncurl.exe -fL -o $archive \"https://github.com/ryancurrah/mcp-gimp/releases/latest/download/$archive\"\ntar -xzf $archive -C $dest\n```\n\nRestart GIMP, then click **Tools > MCP > Start MCP Server** in GIMP's\nmenu bar.\n\nThe macOS binary is unsigned and expects GIMP at `/Applications/GIMP.app`.\n\n### The server\n\n```bash\ngo install github.com/ryancurrah/mcp-gimp/cmd/mcp-gimp@latest\n```\n\nOr grab a binary — same idea, with `mcp-gimp_Linux_x86_64.tar.xz`,\n`mcp-gimp_Darwin_arm64.tar.xz` and so on from the\n[releases page](../../releases):\n\n```bash\ncurl -fL \"https://github.com/ryancurrah/mcp-gimp/releases/latest/download/mcp-gimp_Linux_x86_64.tar.xz\" \\\n  | tar -xJf - --strip-components=1\nsudo install -m 755 mcp-gimp /usr/local/bin/\n```\n\nOr run the [Docker image](#docker).\n\n## Settings\n\nYou usually need none of these. All have `GIMP_`-prefixed environment\nequivalents:\n\n| Flag | Env | Default | Meaning |\n| --- | --- | --- | --- |\n| `-gimp-host` | `GIMP_HOST` | `localhost` | where the plug-in listens |\n| `-gimp-port` | `GIMP_PORT` | `9877` | its port |\n| `-dial-timeout` | `GIMP_DIAL_TIMEOUT` | `10s` | connect timeout |\n| `-call-timeout` | `GIMP_CALL_TIMEOUT` | `120s` | per-operation timeout |\n\nThe plug-in's bind address is chosen in the dialog that **Start MCP Server**\nopens. `GIMP_MCP_BIND_HOST` and `GIMP_MCP_BIND_PORT`, read from GIMP's\nenvironment, set what that dialog starts out with — useful for launching GIMP\npreconfigured:\n\n```bash\nGIMP_MCP_BIND_PORT=9999 gimp\n```\n\nChange the port there and the MCP server needs `-gimp-port` to match.\n\n**Tools > MCP > Stop MCP Server** closes the socket. It reaches the running\nserver over the same port, so if you started on a non-default one, pass it the\nsame port — from Script-Fu, `(plug-in-mcp-server-stop RUN-NONINTERACTIVE\n\"127.0.0.1\" 9999)`.\n\n## Usage\n\nStart with `check_server`. Then work the canvas:\n\n```\nnew_canvas(width=1024, height=768, fill=\"white\")\nfill_ellipse(x=100, y=100, width=200, height=150, color=\"#3366cc\")\nget_state_snapshot(max_size=512)       # look at the canvas, no file written\nexport_image(file_path=\"/abs/path/out.png\")\n```\n\nTwo prompts ship with the server: `gimp_best_practices` and\n`gimp_iterative_workflow`.\n\n### call_api\n\nAnything without a dedicated tool goes through `call_api`, which runs one PDB\nprocedure by name:\n\n```\ndescribe_procedure(api_path=\"gimp-drawable-get-pixel\")\n# -> drawable (GimpDrawable), x-coord (gint), y-coord (gint)\n\ncall_api(api_path=\"gimp-drawable-get-pixel\",\n         kwargs={\"drawable\": 2, \"x-coord\": 10, \"y-coord\": 10})\n```\n\nImages, layers and fonts are passed as integer ids; `-1` means NULL. GIMP\nmatches argument names exactly, so use `describe_procedure` rather than\nguessing. Reference: <https://developer.gimp.org/api/3.0/libgimp/>\n\n> **`call_api` does not evaluate source code.** The plug-in links libgimp,\n> so there is no interpreter inside GIMP to run a snippet in. Anything you\n> would write in GIMP's Python-Fu console is expressed as the procedure it\n> calls: `Gimp.get_images()` becomes `api_path=\"gimp-get-images\"`.\n\n## Docker\n\nThe image contains the server only — the plug-in must run inside your GIMP.\nSo the container has to be able to reach GIMP's socket, and that is the whole\nstory of whether it works:\n\n```bash\n# Linux: the container shares the host's network namespace.\ndocker run --rm -i --network=host ryancurrah/mcp-gimp\n```\n\nOn **Docker Desktop (macOS/Windows)** `host.docker.internal` resolves to the\nhost, but the plug-in binds loopback by default, so the connection is refused.\nEither bind it somewhere reachable:\n\n```bash\nGIMP_MCP_BIND_HOST=0.0.0.0 gimp    # only on a network you trust\n```\n\nor forward the port from the host. File paths are unaffected: `open_image` and\n`export_image` are resolved by GIMP on the host, so no volumes are needed.\n\nRunning the server natively is simpler; the image is for clients that\norchestrate MCP servers as containers.\n\n## Contributing\n\nBuilding from source, adding a tool and how the plug-in works internally are\nin [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Licence\n\nMIT — see [LICENSE](LICENSE).\n\nGIMP itself is GPL-3.0, but the plug-in links only `libgimp`, which is\nLGPL-3.0 and permits linking from differently licensed code.\n"}