gimp-mcp

gimp-mcp

AI-powered control of GIMP 3.x through the Model Context Protocol (MCP).

Talk to GIMP in natural language. Create images, apply filters, manipulate layers, draw shapes — all driven by an AI model through a standardized tool interface.

How it works

┌─────────────┐       stdio/MCP        ┌──────────────────┐      TCP:9876       ┌──────────────────┐
│  AI Client  │ ◄──────────────────────► │  gimp_mcp_server │ ◄──────────────────► │  GIMP 3 Script-Fu│
│  (mcp-cli,  │    JSON-RPC over stdin   │     (Python)     │   GIMP 3 protocol   │     Server       │
│  Claude,    │    /stdout               │                  │   (binary framed)   │  (built-in)      │
│  Cursor...) │                          │  16+ MCP tools   │                     │  900+ PDB procs  │
└─────────────┘                          └──────────────────┘                     └──────────────────┘

No plugin installation required. Uses GIMP's built-in Script-Fu server directly.

The MCP server translates tool calls into Script-Fu (Scheme) expressions, sends them to GIMP over a TCP socket, and returns structured results. Any MCP-compatible AI client can drive GIMP.

Quick start

1. Install the MCP package

pip install "mcp[cli]"

2. Clone this repo

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

3. Start the Script-Fu server in GIMP

Open GIMP 3.x, then:

Filters → Script-Fu → Start Server...

Leave port at 9876, click OK. You should see the server start in the terminal where GIMP was launched.

4. Run with mcp-cli (or any MCP client)

pip install mcp-cli

# Example with DeepSeek on AWS Bedrock:
OPENAI_API_KEY=$AWS_BEARER_TOKEN_BEDROCK \
OPENAI_API_BASE="https://bedrock-mantle.us-east-1.api.aws/v1" \
mcp-cli chat \
  --config-file server_config.json \
  --provider openai_compatible \
  --model deepseek.v3.2 \
  --confirm-mode never \
  --attach gimp3_pdb_reference.md

Integration with AI clients

mcp-cli (any model, any provider)

mcp-cli chat \
  --config-file server_config.json \
  --provider openai_compatible \
  --model <your-model>

Set OPENAI_API_KEY and OPENAI_API_BASE for your provider.

Claude Desktop

Edit ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gimp": {
      "command": "python3",
      "args": ["/absolute/path/to/gimp_mcp_server.py"]
    }
  }
}

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "gimp": {
      "command": "python3",
      "args": ["/absolute/path/to/gimp_mcp_server.py"]
    }
  }
}

5ire

Add the server in the MCP panel:

• Command: python3
• Args: /absolute/path/to/gimp_mcp_server.py

Any OpenAI-compatible API

The server speaks standard MCP over stdio. Point any MCP client at it:

{
  "command": "python3",
  "args": ["/path/to/gimp_mcp_server.py"]
}

Available MCP tools

Tool	Description
list_images	List all open images
get_image_info	Width, height, layers of an image
create_image	New blank RGB image
load_image	Open a file from disk
save_image	Export to disk (format from extension)
flatten_image	Merge all layers
resize_image	Scale to new dimensions
crop_image	Crop to rectangle
flip_image	Horizontal/vertical flip
rotate_image	90°/180°/270° rotation
add_layer	New transparent layer
delete_layer	Remove a layer
set_foreground_color	Set paint color
fill_active_drawable	Fill with foreground color
brightness_contrast	Adjust brightness/contrast
hue_saturation	Adjust HSL
add_text	Add text layer
run_scriptfu	Execute ANY Script-Fu expression

The run_scriptfu tool is a universal escape hatch — it can call any of GIMP's 900+ PDB procedures directly. The AI model uses gimp3_pdb_reference.md as a reference for correct procedure names.

Protocol details

Communication between the MCP server and GIMP uses the Script-Fu server binary protocol:

Request:

'G' (1 byte) + length (uint16 big-endian) + script (utf-8)

Response:

magic (1 byte) + error (1 byte, 0=success) + length (uint16 big-endian) + body (utf-8)

The MCP server opens a new TCP connection per command (thread-safe, no connection state issues).

File structure

gimp-mcp/
├── gimp_mcp_server.py       # MCP server (runs outside GIMP, talks to Script-Fu)
├── gimp3_pdb_reference.md   # Complete PDB reference for AI models
├── server_config.json       # mcp-cli configuration
├── LICENSE
└── README.md

Extending

To add new capabilities, you have two choices:

1. Add a named MCP tool (for common operations):

@mcp.tool()
def sharpen_image(image_id: int, amount: float = 0.5) -> str:
    """Sharpen the active drawable."""
    d = _get_active_drawable(image_id)
    sf(f'(gimp-drawable-brightness-contrast {d} 0.0 {amount})')
    sf("(gimp-displays-flush)")
    return json.dumps({"sharpened": image_id})

2. Use run_scriptfu (for anything — the AI composes the script):

The model can call any GIMP procedure through run_scriptfu. Add procedures to gimp3_pdb_reference.md so the model knows about them.

Requirements

• GIMP 3.0+ (tested on 3.2.4)
• Python 3.10+
• mcp package (pip install "mcp[cli]")
• An MCP-compatible AI client

Supported GIMP installations

Installation	Script-Fu server path	Notes
System package	Just works	GIMP from apt/dnf
Flatpak	Just works	flatpak run org.gimp.GIMP
AppImage	Just works	Download from gimp.org
Snap	May need --network plug	Snap sandboxing

The Script-Fu server binds to localhost:9876 — no firewall or network config needed.

Troubleshooting

"Cannot reach GIMP Script-Fu server" → In GIMP: Filters → Script-Fu → Start Server... → OK

Model uses wrong procedure names → Attach gimp3_pdb_reference.md with --attach flag. Contains all verified GIMP 3 procedure names.

"No tool calls but found tool output" (400 error) → Conversation state corrupted. Exit chat (Ctrl+C) and restart. Use --confirm-mode never to prevent this.

Script-Fu returns "#<EOF>" → The Script-Fu server process is stale. Kill it, restart GIMP, start the server again.

License

MIT