GIMP 3 MCP

gimp3-mcp

gimp3-mcp lets an AI assistant work in a running GIMP 3.2. You describe what you want; the assistant creates or opens images, paints, edits, and exports them, and looks at the image between steps to check its work.

It has two parts: a GIMP plugin that runs inside GIMP, and an MCP server that your AI client (Claude Desktop, Claude Code, or any other MCP client) starts. Together they give the assistant 80 tools, from brush strokes and color adjustments to layers, text, and batch export.

gimp3-mcp started as a fork of gimp-mcp by maorcc and its contributors, and is now developed separately. See Credits and How it differs from gimp-mcp.

---

What you can ask for

Each example is a prompt you can give the assistant, followed by the tools it will typically use.

Paint a picture

Create an 800×800 canvas and paint a ginger cat sitting front-on, in loose painterly strokes.

Look at the canvas after each round of strokes.

`new_canvas` → `paint_stroke` in rounds (textured brushes, tapered strokes, smudging) → `get_state_snapshot` or the `preview` option to look → `sample_color` to pick up colors already on the canvas.

Touch up a photo

Open ~/Pictures/harbor.jpg, auto-level it, add a little contrast and warmth,

sharpen slightly, and export a 2048-pixel-wide JPEG to ~/Pictures/harbor-edit.jpg.

`open_image` → `auto_levels` → `adjust_brightness_contrast` → `adjust_color_balance` → `sharpen` → `scale_to_fit` → `export_image`.

Make a graphic

Make a 1200×630 banner with a dark navy background (#1b2a4a) and the title "Summer Sale"

in large white text with a soft drop shadow, then export it for the web.

`new_canvas` → `add_text` → `apply_drop_shadow` → `export_web_optimized`.

Inspect details

Show me the top-left 300×300 pixels of the current image, enlarged.

get_state_snapshot with a region.

Work with many images

Export every open image as WebP into ~/Desktop/export.

list_images → batch_export.

Anything the tools don't cover

Use GIMP's Python API to list every path in the image and how many strokes each has.

call_api runs Python inside GIMP.

What tool calls look like

The assistant writes these calls, not you, but they show what the tools accept. Each block is the arguments for the named tool.

get_state_snapshot: look at part of an image (coordinates are image pixels; the result is scaled to fit max_size):

{"image_index": 0, "max_size": 512,

"region": {"x": 140, "y": 80, "width": 240, "height": 300}}

paint_stroke: paint a round of strokes and get a preview back:

{"preview": true, "strokes": [

{"points": [[100, 400], [300, 330], [520, 380]], "brush": "Oils 01", "size": 120, "color": "#3b6e8f"}, {"points": [[140, 420], [300, 370]], "brush": "Bristles 02", "size": 40, "color": "#d9a441", "opacity": 80}, {"points": [[250, 360], [330, 350]], "tool": "smudge", "size": 50, "pressure": "none", "strength": 40} ]}

call_api: evaluate Python inside GIMP:

{"api_path": "exec", "args": ["pyGObject-eval", ["len(Gimp.get_images())"]]}

---

How it works

AI client (Claude Desktop, Claude Code, ...)

│ MCP over stdio ▼ gimp_mcp_server.py MCP server: tool definitions and descriptions │ JSON over TCP, localhost:9877 ▼ gimp-mcp-plugin.py GIMP plugin: runs inside GIMP │ PyGObject ▼ GIMP 3.2

The client starts the MCP server. The server turns each tool call into a JSON command and sends it to the plugin, which carries it out with GIMP's Python API and returns the result. The plugin runs one command at a time.

---

Requirements

• GIMP 3.2 (developed and tested with 3.2.6 on macOS)
• [uv](https://docs.astral.sh/uv/), which provides uvx and fetches Python 3.11 or newer when needed
• An MCP client, such as Claude Desktop or Claude Code

---

Installation

1. Install the GIMP plugin

Start GIMP once so it creates its settings folder, then run:

uvx gimp3-mcp install-plugin

This copies the plugin into plug-ins/gimp-mcp-plugin/ inside GIMP's settings folder, and downloads the server so your AI client starts quickly later. It uses the newest GIMP 3.x folder it finds, looking in ~/Library/Application Support/GIMP on macOS, %APPDATA%\GIMP on Windows, and ~/.config/GIMP, ~/snap/gimp/current/.config/GIMP and ~/.var/app/org.gimp.GIMP/config/GIMP on Linux. If your GIMP keeps its settings elsewhere, pass --gimp-dir; Edit > Preferences > Folders > Plug-ins shows the folder GIMP is using. GIMP creates a new settings folder for each minor version, so run the command again after upgrading GIMP. Restart GIMP after installing.

2. Start the plugin's server in GIMP

Choose Tools > MCP > Start MCP Server. No image needs to be open. The server listens on localhost:9877 until GIMP quits, so start it again each time you start GIMP. The same menu has Check MCP Server and Restart MCP Server.

3. Connect your AI client

Claude Desktop. Add the server to claude_desktop_config.json, which is at ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows:

{

"mcpServers": { "gimp": { "command": "uvx", "args": ["gimp3-mcp"] } } }

Quit and reopen Claude Desktop. Claude Desktop lets you turn a connector's tools on and off individually. If the assistant says a tool such as new_canvas isn't available, enable it in the gimp connector's tool settings and start a new chat.

Claude Code.

claude mcp add --scope user gimp -- uvx gimp3-mcp

Other MCP clients. Configure a stdio server with the command uvx and the argument gimp3-mcp.

4. Check the connection

Ask the assistant to "check the GIMP connection". It calls check_server, which reports whether the plugin is reachable and which GIMP version is running.

---

Tools

The server provides 80 tools. Each tool's own description, which the assistant sees, documents its parameters and results.

Seeing the image

Images and files

Painting and drawing

Adjustments

Filters and effects

Transforms

Selections

Layers

Text

Batch and export pipelines

Connection and advanced

| restart_server | Reconnect after GIMP