Skip to content
Back to search

gimp-mcp

GIMP MCP server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/gimp-mcp/gimp-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/gimp-mcp/gimp-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/maorcc--gimp-mcp/badge.svg)](/listings/maorcc--gimp-mcp)

HTML

<a href="/listings/maorcc--gimp-mcp"><img src="/api/listings/maorcc--gimp-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install Dependencies

git clone https://github.com/maorcc/gimp-mcp.git
cd gimp-mcp
uv sync

2. Install the GIMP Plugin

Copy `gimp-mcp-plugin.py` to GIMP's plug-ins directory and restart GIMP.

> **Which directory?** GIMP names its per-user folder after its **major.minor** version > (`3.0`, `3.2`, `3.4`, …) and creates a fresh one on each minor upgrade, so the folder > *moves* when you upgrade GIMP (e.g. `3.0` → `3.2`). The snippet below auto-selects the > newest one, so it keeps working across upgrades. To check the path manually, open GIMP > and look at **Edit → Preferences → Folders → Plug-ins**. > > Launch GIMP at least once before running this, so its config folder exists.

**macOS / Linux:**

# Pick the base directory for your platform:
BASE="$HOME/Library/Application Support/GIMP"     # macOS
# BASE="$HOME/.config/GIMP"                        # Linux (standard)
# BASE="$HOME/snap/gimp/current/.config/GIMP"      # Linux (Snap)

# Auto-select the newest GIMP 3.x config directory (3.0, 3.2, 3.4, ...):
GIMP_DIR="$(ls -d "$BASE"/3.* 2>/dev/null | sort -V | tail -1)"
if [ -z "$GIMP_DIR" ]; then
  echo "No GIMP 3.x config dir found under $BASE — launch GIMP once, then re-run." >&2
  exit 1
fi
mkdir -p "$GIMP_DIR/plug-ins/gimp-mcp-plugin"
cp gimp-mcp-plugin.py "$GIMP_DIR/plug-ins/gimp-mcp-plugin/"
chmod +x "$GIMP_DIR/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py"
echo "Installed into: $GIMP_DIR/plug-ins/gimp-mcp-plugin"

**Windows:**

%APPDATA%\GIMP\<VERSION>\plug-ins\gimp-mcp-plugin\gimp-mcp-plugin.py

Replace `<VERSION>` with your GIMP major.minor (e.g. `3.2`). No chmod needed on Windows. Just copy and restart GIMP.

> For all platforms: [GIMP Plugin Installation Guide](https://en.wikibooks.org/wiki/GIMP/Installing_Plugins)

3. Start the MCP Server in GIMP

1. Open any image in GIMP 2. Go to **Tools > MCP > Start MCP Server** 3. Server starts on `localhost:9877`

4. Configure Your MCP Client

Claude Desktop

`~/.config/Claude/claude_desktop_config.json` (Linux/macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

{
  "mcpServers": {
    "gimp": {
      "command": "uv",
      "args": ["run", "--directory", "/full/path/to/gimp-mcp", "gimp_mcp_server.py"]
    }
  }
}

Claude Code

cd /path/to/gimp-mcp
claude  # .mcp.json is auto-detected

Or manually:

claude mcp add gimp-mcp -- uv run --directory /full/path/to/gimp-mcp gimp_mcp_server.py

Gemini CLI

`~/.config/gemini/.gemini_config.json`:

{
  "mcpServers": {
    "gimp": {
      "command": "uv",
      "args": ["run", "--directory", "/full/path/to/gimp-mcp", "gimp_mcp_server.py"]
    }
  }
}

PydanticAI

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

server = MCPServerStdio('uv', args=['run', '--directory', '/path/to/gimp-mcp', 'gimp_mcp_server.py'])
agent = Agent('openai:gpt-4o', mcp_servers=[server])

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 537 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # GIMP MCP
  2. [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
  3. [![Works with Claude Desktop](https://img.shields.io/badge/Works%20with-Claude%20Desktop-7B2CBF.svg)](https://claude.ai/desktop)
  4. [![GIMP 3.2](https://img.shields.io/badge/GIMP-3.2-orange.svg)](https://gimp.org)
  5. [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
  6. [![CodeRabbit](https://img.shields.io/badge/CodeRabbit-AI%20Review-171717?logo=coderabbit)](https://coderabbit.ai)
  7. ## Demo
  8. ![GIMP MCP in action — AI agent driving GIMP through natural language](docs/mcpInAction.gif)
  9. Full demo (with audio): https://github.com/gimp-mcp/gimp-mcp/raw/main/docs/demo.mp4
  10. *AI agent using GIMP MCP to remove a background, edit a character's expression, and verify results — all through natural language via Claude*
  11. ---
  12. ## Overview
  13. GIMP MCP bridges GIMP's professional image editing capabilities with AI assistants through the [Model Context Protocol](https://modelcontextprotocol.io). It lets you edit images by describing what you want — and gives the AI a live visual feedback channel to verify each change before moving on.
  14. **What makes it different from other GIMP integrations:**
  15. - The AI can *see* the image at any point in the workflow without saving to disk (`get_state_snapshot`)
  16. - Supports fully autonomous multi-step pipelines: open → edit → verify → refine → export
  17. - 79 dedicated tool commands covering every major GIMP operation
  18. - Fully compatible with GIMP 3.2.x (all breaking API changes resolved)
  19. ## Key Features
  20. | | |
  21. |---|---|
  22. | 👁️ **Live Visual Feedback** | `get_state_snapshot` returns a PNG preview mid-workflow so the AI verifies each step |
  23. | 🎨 **79 GIMP Tools** | Adjustments, transforms, selections, layers, drawing, text, filters — all via MCP |
  24. | 🔧 **GIMP 3.2 Compatible** | All GIMP 3.2 API breaks fixed and tested (59/59 passing) |
  25. | 🔁 **Iterative Workflows** | AI loops until a goal is met — e.g. keeps removing BG until no pixels remain |
  26. | 🖼️ **Region Snapshots** | Zoom into any area for detail verification (face, mouth, corner, etc.) |
  27. | 🔌 **Universal MCP** | Works with Claude Desktop, Claude Code, Gemini CLI, PydanticAI, and more |
  28. ## What Can It Do?
  29. ### Background Removal with Iterative Verification
  30. The AI removes the background, takes a snapshot to inspect the result, detects remaining pixels, and loops until the image is clean:
  31. ```
  32. "Remove the background from this image and keep looping until only the character remains"
  33. ```
  34. ### Expression Editing
  35. ```
  36. "Make the character smile — paint a smile arc with teeth over her mouth"
  37. ```
  38. ### Complex Multi-Step Pipelines
  39. ```
  40. "Open navi_portrait.png, remove the background, verify it's clean,
  41. then make her smile and export the final result as a PNG"
  42. ```
  43. ### Color & Tone Work
  44. ```
  45. "Boost the contrast, shift the hue 15 degrees warmer, then show me a before/after zoom of the face"
  46. ```
  47. ### Text & Compositing
  48. ```
  49. "Add a bold title at the top in white with a subtle drop shadow, then export for web"
  50. ```
  51. ---
  52. ## Prerequisites
  53. - **GIMP 3.2+** — tested on GIMP 3.2.2 (Windows, macOS, Linux)
  54. - **uv** — Python package manager ([install uv](https://docs.astral.sh/uv/getting-started/installation/)); `uvx` downloads the MCP server and a suitable Python (3.11+) on first use
  55. - **MCP-compatible AI client** — Claude Desktop, Claude Code, Gemini CLI, PydanticAI, etc.
  56. ---
  57. ## Quick Start
  58. The MCP server and the GIMP plugin ship together as the [`gimp-mcp-plugin`](https://pypi.org/project/gimp-mcp-plugin/) package on PyPI. No clone needed.
  59. ### 1. Install the GIMP Plugin
  60. Launch GIMP once (so its config folder exists), close it, then run:
  61. ```bash
  62. uvx gimp-mcp-plugin@latest install-plugin
  63. ```
  64. This copies the plugin into the newest GIMP 3.x config folder it finds (Linux standard, Snap and Flatpak locations, macOS, Windows) and makes it executable. Restart GIMP afterward.
  65. - `--dry-run` shows where it would install without writing anything.
  66. - `--gimp-dir DIR` installs into a specific GIMP config folder, e.g. `--gimp-dir ~/.config/GIMP/3.2`.
  67. If you have more than one GIMP 3 installation (e.g. a system GIMP and a Flatpak), the newest folder found may not be the one your GIMP uses. Check the folder shown in GIMP's **Edit → Preferences → Folders → Plug-ins** and pass the folder that contains `plug-ins` with `--gimp-dir`.
  68. > **Which folder does GIMP use?** GIMP names its per-user folder after its **major.minor**
  69. > version (`3.0`, `3.2`, `3.4`, …) and creates a fresh one on each minor upgrade, so the
  70. > plug-ins folder *moves* when you upgrade GIMP. Re-run `install-plugin` after upgrading.
  71. > To check the active path, open **Edit → Preferences → Folders → Plug-ins** in GIMP.
  72. ### 2. Start the MCP Server in GIMP
  73. 1. Open any image in GIMP
  74. 2. Go to **Tools > MCP > Start MCP Server**
  75. 3. Server starts on `localhost:9877`
  76. #### Start automatically when GIMP launches
  77. To skip step 2 on every launch, open **Tools > MCP > MCP Server Settings...**, tick
  78. **Start MCP server when GIMP launches**, and restart GIMP. Autostart is off by default.
  79. The same dialog sets the **port** (default `9877`). If you change it, set `GIMP_MCP_PORT`
  80. in your MCP client config so the MCP server connects to the same port:
  81. ```json
  82. "gimp": {
  83. "command": "uvx",
  84. "args": ["gimp-mcp-plugin@latest"],
  85. "env": { "GIMP_MCP_PORT": "9988" }
  86. }
  87. ```
  88. Settings are saved to `gimp-mcp.json` in GIMP's per-user config folder (e.g.
  89. `~/.config/GIMP/3.2/gimp-mcp.json`). Port changes apply the next time the server starts.
  90. #### Timeout for long commands
  91. The MCP server waits up to 300 seconds for GIMP to finish each command. For heavier work
  92. (large or 16-bit images, slow filters), set `GIMP_MCP_TIMEOUT` (in seconds) in your MCP
  93. client config, the same way as `GIMP_MCP_PORT` above, e.g. `"GIMP_MCP_TIMEOUT": "900"`.
  94. `check_server` reports the timeout in effect. When a command times out, GIMP may still be
  95. running it, so check the image before retrying. Your MCP client may have its own tool
  96. timeout (in Claude Code, `MCP_TOOL_TIMEOUT`, in milliseconds); raise it too if it's shorter.
  97. ### 3. Configure Your MCP Client
  98. `gimp-mcp-plugin@latest` makes `uvx` check PyPI for a new release each time your client starts the server.
  99. #### Claude Desktop
  100. `~/.config/Claude/claude_desktop_config.json` (Linux/macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
  101. ```json
  102. {
  103. "mcpServers": {
  104. "gimp": {
  105. "command": "uvx",
  106. "args": ["gimp-mcp-plugin@latest"]
  107. }
  108. }
  109. }
  110. ```
  111. #### Claude Code
  112. ```bash
  113. claude mcp add gimp-mcp -- uvx gimp-mcp-plugin@latest
  114. ```
  115. #### Gemini CLI
  116. `~/.config/gemini/.gemini_config.json`:
  117. ```json
  118. {
  119. "mcpServers": {
  120. "gimp": {
  121. "command": "uvx",
  122. "args": ["gimp-mcp-plugin@latest"]
  123. }
  124. }
  125. }
  126. ```
  127. #### PydanticAI
  128. ```python
  129. from pydantic_ai import Agent
  130. from pydantic_ai.mcp import MCPServerStdio
  131. server = MCPServerStdio('uvx', args=['gimp-mcp-plugin@latest'])
  132. agent = Agent('openai:gpt-4o', mcp_servers=[server])
  133. ```
  134. #### Cancelling long commands
  135. GIMP runs one command at a time, in the order they're sent. While it works, the MCP server
  136. stays responsive, so your client can cancel a call. The cancel returns at once: a command
  137. that's still waiting its turn never runs, but one GIMP has already started is finished in
  138. the background. Check the image before retrying a cancelled edit, or it may be applied twice.
  139. ### Updating
  140. The plugin and the MCP server must be the same version. `check_server` and `get_gimp_info` report a mismatch and print the command that fixes it. To update both:
  141. 1. Restart your MCP client. With `@latest`, it picks up the newest server.
  142. 2. Run `uvx gimp-mcp-plugin@latest install-plugin` and restart GIMP.
  143. ### Running from a Git Checkout (contributors)
  144. To work on the code, run the server and install the plugin from a clone instead:
  145. ```bash
  146. git clone https://github.com/gimp-mcp/gimp-mcp.git
  147. cd gimp-mcp
  148. uv sync
  149. uv run gimp_mcp_server.py install-plugin # installs this checkout's plugin
  150. ```
  151. Then point your MCP client at the checkout, e.g. for Claude Desktop:
  152. ```json
  153. "gimp": {
  154. "command": "uv",
  155. "args": ["run", "--directory", "/full/path/to/gimp-mcp", "gimp_mcp_server.py"]
  156. }
  157. ```
  158. Claude Code picks up the repo's `.mcp.json` automatically when started in the checkout. After `git pull`, re-run `install-plugin` if the plugin changed.
  159. ---
  160. ## Available MCP Tools
  161. ### 👁️ Visual Feedback
  162. #### `get_state_snapshot(image_index, max_size, region, label)`
  163. Returns a live PNG of the current image state — the AI's primary feedback mechanism. Call this between any edits to verify the result without saving to disk.
  164. ```python
  165. # Full image snapshot
  166. snapshot = get_state_snapshot(max_size=512)
  167. # Zoom into a face region for detail inspection
  168. snapshot = get_state_snapshot(
  169. region={"x": 140, "y": 80, "width": 240, "height": 300},
  170. max_size=512,
  171. label="face-check"
  172. )
  173. ```
  174. This enables iterative agentic workflows: **edit → snapshot → assess → refine → repeat**.
  175. #### `get_image_bitmap(image_index, max_width, max_height, region)`
  176. Lower-level bitmap fetch with region extraction and scaling. Returns base64-encoded PNG.
  177. ### 🎨 Adjustments
  178. | Tool | Description |
  179. |---|---|
  180. | `adjust_brightness_contrast` | Brightness and contrast |
  181. | `adjust_curves` | Curves by channel (RGB/R/G/B/A) |
  182. | `adjust_hue_saturation` | Hue, saturation, lightness |
  183. | `adjust_color_balance` | Shadows/midtones/highlights color balance |
  184. | `auto_levels` | Auto-stretch levels |
  185. | `desaturate` | Convert to grayscale (keep RGB mode) |
  186. | `invert_colors` | Invert all channels |
  187. | `convert_color_mode` | Convert between RGB, grayscale, and indexed modes |
  188. | `sharpen` | Unsharp mask sharpening |
  189. | `blur` | Gaussian blur |
  190. | `denoise` | Noise reduction |
  191. ### 🔄 Transforms
  192. | Tool | Description |
  193. |---|---|
  194. | `scale_image` | Scale to exact dimensions |
  195. | `scale_to_fit` | Scale within bounding box (aspect-safe) |
  196. | `crop_to_rect` | Crop to rectangle |
  197. | `crop_to_selection` | Crop canvas to the current selection bounds |
  198. | `rotate_image` | Rotate 90/180/270 or arbitrary angle |
  199. | `flip_image` | Flip horizontal or vertical |
  200. | `resize_canvas` | Resize canvas without scaling content |
  201. | `warp_region` | Warp / liquify a region by pushing pixels in a direction |
  202. ### ✂️ Selections
  203. | Tool | Description |
  204. |---|---|
  205. | `select_rectangle` | Rectangular marquee |
  206. | `select_ellipse` | Elliptical marquee |
  207. | `select_by_color` | Select by color (global) |
  208. | `select_all` / `select_none` | Select all / deselect |
  209. | `invert_selection` | Invert selection |
  210. | `modify_selection` | Grow, shrink, feather, or border |
  211. ### 🗂️ Layers
  212. | Tool | Description |
  213. |---|---|
  214. | `create_layer` | New empty layer |
  215. | `duplicate_layer` | Duplicate active layer |
  216. | `delete_layer` | Delete named layer |
  217. | `rename_layer` | Rename layer |
  218. | `set_layer_properties` | Opacity, blend mode, visibility |
  219. | `reorder_layer` | Move layer in stack |
  220. | `merge_visible_layers` | Flatten visible to one layer |
  221. | `flatten_image` | Flatten all layers |
  222. | `list_layers` | List all layers with properties |
  223. ### 🖌️ Drawing & Fill
  224. | Tool | Description |
  225. |---|---|
  226. | `fill_layer` | Fill entire layer with color |
  227. | `fill_selection` | Fill selection (foreground/background/transparent) |
  228. | `fill_rectangle` | Fill a rectangle region |
  229. | `fill_ellipse` | Fill an ellipse region |
  230. | `draw_line` | Draw a line (pencil or paintbrush) |
  231. | `draw_rectangle` | Draw a rectangle outline |
  232. | `draw_ellipse` | Draw an ellipse outline |
  233. | `gradient_fill` | Apply linear or radial gradient |
  234. | `set_colors` | Set foreground/background colors |
  235. ### 🔤 Text
  236. | Tool | Description |
  237. |---|---|
  238. | `add_text` | Add a text layer |
  239. | `edit_text` | Edit existing text layer |
  240. | `list_fonts` | List available fonts |
  241. ### ✨ Filters & Effects
  242. | Tool | Description |
  243. |---|---|
  244. | `apply_gaussian_blur` | Gaussian blur filter |
  245. | `apply_pixelate` | Pixelate/mosaic effect |
  246. | `apply_emboss` | Emboss effect |
  247. | `apply_vignette` | Vignette darkening |
  248. | `apply_noise` | Add noise/grain |
  249. | `apply_drop_shadow` | Drop shadow effect |
  250. ### 📁 File Operations
  251. | Tool | Description |
  252. |---|---|
  253. | `open_image` | Open image file |
  254. | `open_image_as_layer` | Import an image file as a new layer in an open image |
  255. | `export_image` | Export to PNG, JPEG, WebP, TIFF, BMP |
  256. | `save_xcf` | Save as GIMP XCF (preserves layers and metadata) |
  257. | `new_canvas` | Create blank canvas |
  258. | `close_image` | Close image |
  259. | `list_images` | List open images |
  260. | `set_active_image` | Bring a specific open image to the front |
  261. ### 📦 Batch & Multi-Format Export
  262. | Tool | Description |
  263. |---|---|
  264. | `batch_export` | Export all open images (or one) to a directory |
  265. | `batch_resize` | Resize all open images to a common size |
  266. | `export_web_optimized` | Export as JPEG and PNG, keeping the smaller |
  267. | `export_icon_sizes` | Export a full Android or iOS icon set |
  268. | `export_social_media_kit` | Export resized versions for social media platforms |
  269. | `export_sprite_sheet` | Combine frames into a sprite sheet PNG |
  270. ### ↩️ History
  271. | Tool | Description |
  272. |---|---|
  273. | `undo` | Not supported on GIMP 3.x: returns an error (use Ctrl+Z in GIMP) |
  274. | `redo` | Not supported on GIMP 3.x: returns an error (use Ctrl+Y in GIMP) |
  275. ### 🔍 Info & Context
  276. | Tool | Description |
  277. |---|---|
  278. | `get_image_metadata` | Image size, mode, layers, filename |
  279. | `get_gimp_info` | GIMP version, platform, capabilities |
  280. | `get_context_state` | Current colors, brush, opacity, mode |
  281. | `get_pixel_color` | Color value at a specific pixel |
  282. | `get_histogram` | Histogram data for a channel |
  283. | `get_selection_bounds` | Current selection bounds |
  284. ### 🔌 Connection & Raw API
  285. | Tool | Description |
  286. |---|---|
  287. | `check_server` | Check the GIMP plugin socket is reachable and that the plugin version matches the server |
  288. | `restart_server` | Drop and re-establish the connection to the plugin |
  289. | `call_api` | Run arbitrary Python-Fu code inside GIMP (escape hatch for anything not covered above) |
  290. ---
  291. ## AI Agent Feedback Loop
  292. The `get_state_snapshot` tool enables a pattern where the AI loops until a goal is visually confirmed:
  293. ```text
  294. ┌─────────────┐
  295. │ Apply edit │
  296. └──────┬──────┘
  297. │
  298. ▼
  299. ┌─────────────────┐
  300. │ get_state_ │ ← AI sees live PNG, no disk save needed
  301. │ snapshot() │
  302. └──────┬──────────┘
  303. │
  304. ▼
  305. ┌─────────────────┐ ┌──────────────────┐
  306. │ Goal achieved? │─ No─▶ Adjust & retry │
  307. └──────┬──────────┘ └──────────────────┘
  308. │ Yes
  309. ▼
  310. ┌─────────────┐
  311. │ Export │
  312. └─────────────┘
  313. ```
  314. ### Example: Iterative Background Removal
  315. See [`bg_remove_iterative.py`](bg_remove_iterative.py) for a complete example. The AI:
  316. 1. Removes the background using edge-seeded contiguous select
  317. 2. Takes a snapshot to check the result
  318. 3. Scans for remaining background-colored pixels
  319. 4. Runs targeted removal passes with progressively finer grids (25px → 1px)
  320. 5. Runs a final despeckle pass for isolated pixels
  321. 6. Loops until no background pixels remain
  322. ---
  323. ## Example Scripts
  324. | Script | Description |
  325. |---|---|
  326. | [`run_tests.py`](run_tests.py) | 59-test suite — run against your GIMP to verify all tools work |
  327. | [`bg_remove_iterative.py`](bg_remove_iterative.py) | Iterative BG removal with snapshot checkpoints |
  328. | [`bg_remove.py`](bg_remove.py) | Simple single-pass background removal |
  329. | [`agent_edit_demo.py`](agent_edit_demo.py) | Full pipeline: open → remove BG → edit expression → export |
  330. | [`tests/test_add_text_metadata.py`](tests/test_add_text_metadata.py) | Regression test: `add_text` returns real layer metadata |
  331. | [`tests/continuous_edit_test/continuous_edit_test.py`](tests/continuous_edit_test/continuous_edit_test.py) | End-to-end agent editing loop: BG removal, selective recolor, composite |
  332. Run the test suite to verify your setup:
  333. ```bash
  334. python run_tests.py
  335. # Expected: 59/59 PASSED
  336. ```
  337. ---
  338. ## Technical Architecture
  339. ### Plugin ↔ Server Communication
  340. ```text
  341. AI Client (Claude, etc.)
  342. │ MCP (stdio)
  343. ▼
  344. gimp_mcp_server.py ← MCP tool definitions
  345. │ TCP JSON :9877
  346. ▼
  347. gimp-mcp-plugin.py ← Runs inside GIMP process
  348. │ PyGObject
  349. ▼
  350. GIMP 3.2 (gi.repository.Gimp)
  351. ```
  352. - MCP server translates tool calls into JSON commands sent to the plugin over TCP
  353. - Plugin executes operations directly in the GIMP process via PyGObject
  354. - Two message formats: `{"type": "...", "params": {...}}` for named tools, `{"cmds": ["python..."]}` for arbitrary exec
  355. ### GIMP 3.2 Compatibility Notes
  356. GIMP 3.x introduced breaking API changes from GIMP 2.x. Key fixes included in this release:
  357. | Issue | Fix |
  358. |---|---|
  359. | `layer.copy(False)` → error | `layer.copy()` takes no args in GIMP 3.2 |
  360. | `Gimp.text_fontname()` removed | Use PDB `gimp-text-fontname` |
  361. | `gimp-blend` removed | Use GEGL `gegl:linear-gradient` / `gegl:radial-gradient` |
  362. | `GimpDoubleArray` TypeError in curves | Use `drawable.curves_spline()` directly |
  363. | `Gimp.fonts_get_list()` returns `Font` objects | Convert via `.get_name()` before JSON serialization |
  364. | `image.select_none()` removed | Use PDB `gimp-selection-none` |
  365. | `layer.get_pixel()` returns `Gegl.Color` | Use `.get_rgba()` to extract float components |
  366. ---
  367. ## Troubleshooting
  368. ### "Could not connect to GIMP"
  369. - GIMP must be running with an image open
  370. - Start the MCP server: **Tools > MCP > Start MCP Server**, or enable autostart in **Tools > MCP > MCP Server Settings...**
  371. - If you changed the port in GIMP, set `GIMP_MCP_PORT` to the same value in your MCP client config
  372. - Check port 9877 (or your custom port) is not blocked by firewall
  373. ### "GIMP did not reply within 300 s"
  374. - The command took longer than the MCP server waits. Raise `GIMP_MCP_TIMEOUT` (seconds) in your MCP client config; see [Timeout for long commands](#timeout-for-long-commands)
  375. - GIMP may still be running the command: check the image before retrying
  376. ### Plugin Not Visible in GIMP
  377. - Look under **Tools > MCP** (the plugin adds an `MCP` submenu, not a top-level `Tools` entry)
  378. - Confirm the plugin file is in the correct directory: `uvx gimp-mcp-plugin@latest install-plugin --dry-run` shows where it goes
  379. - **Upgraded GIMP recently?** A minor upgrade (e.g. 3.0 → 3.2) moves the per-user config folder to a new version directory; re-run `uvx gimp-mcp-plugin@latest install-plugin` (use `--dry-run` to see which folder it picks). Verify the active path via **Edit > Preferences > Folders > Plug-ins**.
  380. - On Linux/macOS: ensure the file has execute permission (`chmod +x`)
  381. - Restart GIMP after installation
  382. - Check **Filters > Script-Fu > Console** for error messages
  383. ### Tests Failing
  384. Run the test suite and check the failure list:
  385. ```bash
  386. python run_tests.py
  387. ```
  388. Each failure includes the tool name and error — most issues on GIMP 3.2 are covered by the fixes above.
  389. ---
  390. ## Example Output
  391. <img src="gimp-screenshot1.png" alt="GIMP MCP Example" width="400">
  392. *"Draw me a face and a sheep" — generated entirely through natural language via GIMP MCP*
  393. ---
  394. ## Future Enhancements
  395. - **📚 Recipe Collection**: Reusable workflow templates (portrait cleanup, product photo, etc.)
  396. - **🚀 Dynamic Discovery**: Auto-generate MCP tools from GIMP's full PDB procedure database
  397. - **🔒 Security**: Sandboxed execution for untrusted command inputs
  398. - **⚡ Performance**: Optimized bitmap transfer for large images
  399. - **🌐 Remote Access**: Network-accessible GIMP instances
  400. ---
  401. ## Contributing
  402. Contributions are welcome — bug fixes, new tools, documentation, or example scripts. Open a PR or issue on GitHub.
  403. ### Development Setup
  404. Install dev dependencies and activate the pre-commit hook so `ruff` runs on every commit:
  405. ```bash
  406. uv sync
  407. uv run pre-commit install
  408. ```
  409. After this, `ruff` checks staged files on each `git commit` (with `--fix` applied automatically). The same check runs in CI, so the hook is just a fast local safety net.
  410. To bump the pinned hook versions later:
  411. ```bash
  412. uv run pre-commit autoupdate
  413. ```
  414. ## License
  415. GPL-3.0-or-later. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.