GIMP MCP Server 🎨

⚠️ Work in Progress: This project is functional but still under active development. While the core features are working, thorough testing and additional functionality are being added. Expect changes and improvements in upcoming releases.

A Model Context Protocol (MCP) server that enables live control of GIMP through natural language instructions. This allows AI assistants like Claude to directly manipulate images in real-time.

✨ Features

• 🎯 Live Instance Control - Direct manipulation of running GIMP documents
• ⚡ D-Bus Integration - Real-time communication with GIMP 3
• 🐍 Python Code Execution - Run arbitrary GIMP API code in live context
• 📊 Document Info - Get image dimensions, layers, and properties
• 📸 Screenshot Support - Visual feedback with viewport capture
• 🔄 Automatic Setup - Virtual environment created on first run

🖥️ Platform Support

• ⚠️ Currently Linux Only - Uses D-Bus which is Linux-specific
• Requires GIMP 3 - Uses new Python 3 plugin architecture with GObject Introspection

🚀 Quick Start

1. Install GIMP D-Bus Bridge Plugin

1. Go to the Releases page
2. Download gimpmcp-plugin.zip from the latest release
3. Extract to your GIMP plugins directory:

   cd ~/.config/GIMP/3.0/plug-ins/
   unzip ~/Downloads/gimpmcp-plugin.zip
   chmod +x gimpmcp/gimpmcp.py
   chmod +x gimpmcp/gimpmcp/run_gimp_mcp.sh

2. Start GIMP and Enable D-Bus Service

1. Launch GIMP:

   gimp

2. Enable MCP D-Bus service in GIMP:

   • Go to: Filters > Development > MCP D-Bus - Start
   • ✅ The service will remain active until you close GIMP
   • You only need to do this once per GIMP session

3. Connect with AI Tools

Auto-Setup: The first time an AI client connects, it will automatically:

• Create Python virtual environment in gimpmcp/venv/
• Install all required dependencies from requirements.txt
• Start the MCP server

No manual setup required!

Claude Code

Edit your Claude configuration file (~/.claude.json):

{
  "mcpServers": {
    "gimp-mcp": {
      "type": "stdio",
      "command": "/path/to/gimpmcp/gimpmcp/run_gimp_mcp.sh",
      "args": [],
      "env": {}
    }
  }
}

Anthropic Claude Desktop

Update Claude desktop app settings:

{
  "mcpServers": {
    "gimp-mcp": {
      "command": "/path/to/gimpmcp/gimpmcp/run_gimp_mcp.sh"
    }
  }
}

Google Gemini/Codex

For Gemini, edit settings file (~/.gemini/settings.json):

{
  "mcpServers": {
    "gimp-mcp": {
      "command": "/path/to/gimpmcp/gimpmcp/run_gimp_mcp.sh"
    }
  }
}

For Codex, edit configuration (~/.codex/config.toml):

[mcp_servers.gimp-mcp]
command = "/path/to/gimpmcp/gimpmcp/run_gimp_mcp.sh"

📚 Usage

With AI Assistants

Once configured, you can use natural language to control GIMP:

Create a new 800x600 image with a red circle in the center

Get information about the current document

Take a screenshot of the current viewport

Manual Testing with CLI

The client can also be used directly for manual testing:

# Get document info
python gimpmcp_client.py get-info ""

# Get viewport screenshot
python gimpmcp_client.py get-viewport-screenshot "format=png max_size=400"

# Execute Python code
python gimpmcp_client.py execute-code "code='print(\"Hello GIMP\")'"

# Execute code from file
python gimpmcp_client.py execute-code -f my_script.py

# Get structured JSON output
python gimpmcp_client.py get-info "" --parse-out --pretty

🏗️ Architecture

The GIMP MCP follows a clean architecture pattern:

AI Client → MCP Server → CLI Client → D-Bus → GIMP Plugin → Live Document

• gimpmcp.py: GIMP 3 plugin that exposes D-Bus interface
• gimpmcp/gimp_mcp_server.py: MCP server with tool definitions and docstrings for AI
• gimpmcp/gimpmcp_client.py: Client that handles all command logic (used by both server and manual testing)
• gimpmcp/run_gimp_mcp.sh: Wrapper script for automatic venv setup

Key Design: No code duplication! The server simply wraps client functions with MCP tool decorators. The same code runs for both AI assistant usage and manual CLI testing.

🎨 Available Context in Code Execution

When your code executes in GIMP, you have access to:

• Gimp - Main GIMP module (gi.repository.Gimp)
• GimpUi - GIMP UI module
• Gegl - GEGL image processing library
• GObject, Gio, GLib - GTK/GNOME libraries
• image - The active GIMP image object
• drawables - List of selected drawables
• pdb - GIMP Procedural Database (Gimp.get_pdb())

💡 Examples

Layer Operations

# Get active layer
layer = image.get_active_layer()
print(f"Active layer: {layer.get_name() if layer else 'None'}")

# Create new layer
new_layer = Gimp.Layer.new(
    image,
    "AI Generated Layer",
    image.get_width(),
    image.get_height(),
    Gimp.ImageType.RGBA_IMAGE,
    100.0,
    Gimp.LayerMode.NORMAL
)
image.insert_layer(new_layer, None, 0)

# Set layer opacity
layer.set_opacity(50.0)

Using Procedural Database

# Invert colors
procedure = pdb.lookup_procedure("gimp-drawable-invert")
config = procedure.create_config()
config.set_property("drawable", image.get_active_layer())
procedure.run(config)

# Apply Gaussian blur
procedure = pdb.lookup_procedure("plug-in-gauss")
config = procedure.create_config()
config.set_property("run-mode", Gimp.RunMode.NONINTERACTIVE)
config.set_property("image", image)
config.set_property("drawable", image.get_active_layer())
config.set_property("horizontal", 5.0)
config.set_property("vertical", 5.0)
procedure.run(config)

Selections and Filling

# Create rectangular selection
image.select_rectangle(Gimp.ChannelOps.REPLACE, 100, 100, 300, 200)

# Set foreground color
Gimp.context_set_foreground(Gegl.Color.new("red"))

# Fill selection
layer = image.get_active_layer()
procedure = pdb.lookup_procedure("gimp-drawable-edit-fill")
config = procedure.create_config()
config.set_property("drawable", layer)
config.set_property("fill-type", Gimp.FillType.FOREGROUND)
procedure.run(config)

# Remove selection using PDB
procedure = pdb.lookup_procedure("gimp-selection-none")
config = procedure.create_config()
config.set_property("image", image)
procedure.run(config)

# Update display
Gimp.displays_flush()

Image Information

# Get image dimensions
width = image.get_width()
height = image.get_height()
print(f"Image size: {width}x{height}")

# List all layers
layers = image.get_layers()
for layer in layers:
    print(f"Layer: {layer.get_name()}")

🔧 How It Works

1. MCP Server receives request - AI client sends command
2. Server calls client function - Uses shared execute_gimp_command() from client
3. Client builds code - Generates Python code for the command
4. D-Bus call - Client calls D-Bus method ExecuteCode on org.gimp.mcp.Bridge
5. Plugin receives request - GIMP plugin handles D-Bus method call
6. Execute in GIMP - Code executes with full GIMP API access
7. Return response - Plugin returns result via D-Bus
8. Format and return - Server formats response for AI client

🎯 D-Bus Service Details

• Service Name: org.gimp.mcp.Bridge
• Object Path: /org/gimp/mcp/Bridge
• Interface: org.gimp.mcp.Bridge
• Method: ExecuteCode(code: str) -> str (returns JSON)

Test D-Bus service directly:

# Check if service is running
gdbus introspect --session --dest org.gimp.mcp.Bridge --object-path /org/gimp/mcp/Bridge

# List registered services
gdbus list | grep org.gimp.mcp.Bridge

# Execute code
gdbus call --session --dest org.gimp.mcp.Bridge --object-path /org/gimp/mcp/Bridge --method org.gimp.mcp.Bridge.ExecuteCode 'print("Hello GIMP")'

🐛 Troubleshooting

Service not available

• ✅ Make sure GIMP is running
• ✅ Enable MCP D-Bus service: Filters > Development > MCP D-Bus - Start
• ✅ Check service is registered: gdbus list | grep org.gimp.mcp.Bridge

D-Bus connection errors in sandboxed environments

The run_gimp_mcp.sh script automatically sets required environment variables:

• XDG_RUNTIME_DIR
• DBUS_SESSION_BUS_ADDRESS

Plugin not appearing in menu

• Check that folder name and file name match: gimpmcp/gimpmcp.py
• Make sure the file is executable: chmod +x gimpmcp/gimpmcp.py
• Restart GIMP

📖 GIMP 3 API Resources

• GIMP 3.0 API Reference
• Python Plugin Tutorial
• GObject Introspection

📝 License

GPL-3.0