GIMP MCP Server

Control GIMP from Claude Desktop, Codex, Cursor, and other Model Context Protocol clients. This project provides a local MCP server and a GIMP 3.x Python plug-in that expose GIMP automation through a secure Unix socket, including Procedure Database discovery, image export, canvas snapshots, context inspection, and batch operations.

Keywords: GIMP MCP, GIMP Model Context Protocol, Claude GIMP, Codex GIMP, AI image editing, GIMP automation, GIMP Python plug-in, GIMP PDB, MCP server.

Why This Exists

GIMP has a powerful Python and Procedure Database API, but it is not easy for AI assistants to use directly. GIMP MCP bridges that gap:

• Ask an AI assistant to inspect or edit images in GIMP.
• Search and call GIMP PDB procedures from MCP tools.
• Capture the current canvas as MCP image content for visual verification.
• Run repeatable image workflows without clicking through the GIMP UI.
• Keep automation local by default with a user-owned Unix socket.

The normal MCP path auto-starts a private headless GIMP bridge, so users do not need to open GIMP or click Filters > Development.

Features

• GIMP 3.x automation through MCP
• PDB search, describe, and call for broad GIMP feature coverage
• MCP image capture with optional crop and max-size scaling
• Open image and layer inspection
• First-class layer tools for listing and updating layer properties
• Friendly drawing tools for rectangles, ellipses, text, and polylines
• Foreground/background, brush, font, opacity, antialias, and feather state
• File open/export helpers for PNG, JPEG, WebP, TIFF, GIF, BMP, and XCF
• Batch bridge operations
• Headless auto-start for production-style automation
• Manual visible-GIMP bridge for debugging interactive sessions
• macOS-friendly installer for /Applications/GIMP.app

Requirements

• GIMP 3.x installed locally
• Python 3.11+
• An MCP-compatible client such as Codex, Claude Desktop, Cursor, or another stdio MCP client

This repo defaults to macOS and /Applications/GIMP.app. The bridge itself is Python/GIMP based and can be adapted for Linux by installing the plug-in into the relevant GIMP profile directory.

Quick Start

git clone https://github.com/abelduarte/gimp-mcp.git
cd gimp-mcp

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

./scripts/install_bridge.sh
./scripts/smoke_test.sh

If GIMP is not installed at /Applications/GIMP.app:

GIMP_APP=/path/to/GIMP.app ./scripts/install_bridge.sh
GIMP_APP=/path/to/GIMP.app ./scripts/smoke_test.sh

MCP Client Configuration

Use the wrapper script as your MCP server command:

/absolute/path/to/gimp-mcp/scripts/run_mcp_server.sh

The wrapper starts the stdio MCP server and automatically launches a private headless GIMP bridge if one is not already running.

Codex

Add this to your Codex MCP config:

[mcp_servers.gimp]
command = "/absolute/path/to/gimp-mcp/scripts/run_mcp_server.sh"

Claude Desktop

Add this to your Claude Desktop config:

{
  "mcpServers": {
    "gimp": {
      "command": "/absolute/path/to/gimp-mcp/scripts/run_mcp_server.sh"
    }
  }
}

Project-local MCP discovery

The repository includes .mcp.json for clients that support project-local MCP server discovery.

How It Works

There are two pieces:

• gimp_mcp.server: the stdio MCP server used by the AI client.
• bridge/gimp_mcp_bridge.py: a GIMP Python plug-in that runs inside GIMP and exposes a JSON bridge over a local Unix socket.

Default socket:

/tmp/gimp-mcp-$USER.sock

The socket is created with 0600 permissions. Anyone who can connect to it can drive the GIMP process, so do not expose it to untrusted users.

Available Tools

• gimp.status: check bridge health
• gimp.get_info: inspect GIMP version, directories, session, platform, and PDB
• gimp.get_context_state: inspect colors, brush, opacity, font, antialias, and feather
• gimp.get_image_bitmap: return a GIMP image as MCP image content
• gimp.list_images: list open images and layer trees
• gimp.get_image: inspect one image by ID
• gimp.list_layers: list layers for one image
• gimp.set_layer_properties: rename layers or update visibility, opacity, and blend mode
• gimp.procedure.search: search GIMP's Procedure Database
• gimp.procedure.describe: inspect procedure arguments and return values
• gimp.procedure.call: call a GIMP PDB procedure
• gimp.open: open an image file
• gimp.export: export an image file
• gimp.fill_rect: fill a rectangle on a drawable
• gimp.fill_ellipse: fill an ellipse on a drawable
• gimp.add_text: create a text layer
• gimp.draw_polyline: draw deterministic pixel polylines
• gimp.batch: run bridge operations in sequence

Example PDB Call

Search before calling:

{
  "query": "image-resize",
  "limit": 10
}

Then call the procedure with exact PDB argument names:

{
  "name": "gimp-image-resize",
  "args": {
    "image": { "id": 1, "type": "image" },
    "new-width": 1920,
    "new-height": 1080,
    "offx": 0,
    "offy": 0
  }
}

Visual Verification

Use gimp.get_image_bitmap to let the AI client see the current GIMP image:

{
  "image_id": 1,
  "max_width": 1024,
  "max_height": 1024
}

Crop a region for faster iteration:

{
  "image_id": 1,
  "region": {
    "origin_x": 100,
    "origin_y": 100,
    "width": 400,
    "height": 300
  },
  "max_width": 800,
  "max_height": 600
}

Manual Visible-GIMP Mode

For normal automation, use scripts/run_mcp_server.sh. It auto-starts a headless bridge.

For debugging against the visible GIMP app:

1. Open GIMP.
2. Run Filters > Development > Start MCP Bridge.
3. Start your MCP client with the same GIMP_MCP_SOCKET.

This manual menu is a debug fallback, not the recommended production path.

Development

Run the smoke test:

./scripts/smoke_test.sh

Run full local diagnostics:

./scripts/doctor.sh

Compile-check the Python files:

python3 -m py_compile src/gimp_mcp/server.py bridge/gimp_mcp_bridge.py

Install the bridge after editing it:

./scripts/install_bridge.sh

Examples

Generated examples are in examples/generated/, including:

• horse-from-gimp-mcp.png
• bar-chart-from-gimp-mcp.png
• shapes-text-demo.png

Security

GIMP MCP is a local automation bridge. Treat access to the Unix socket as access to the running GIMP process.

• Do not expose the socket to untrusted users.
• Do not run the bridge as root.
• Prefer the default Unix socket transport over TCP.
• Review SECURITY.md before enabling any future raw Python execution feature.

License

MIT. See LICENSE.