iflow-mcp_maorcc-gimp-mcp 0.1.0

GIMP MCP integration for external control of GIMP 3.0

GIMP MCP

Overview

This project enables non-technical users to edit images with GIMP through simple conversational commands, bridging the gap between GIMP's powerful capabilities and natural language interaction. It also allows professionals to execute complex multi-step workflows faster than traditional point-and-click methods.

Users can describe what they want to achieve - from basic photo adjustments to sophisticated artistic modifications. For example, "brighten the background and add a vintage filter" or "remove the red-eye and sharpen the subject" - and the system translates these requests into precise GIMP operations.

The project is fully functional and exposes all GIMP features via MCP (Model Context Protocol). New in this version: MCP-compliant image export that allows AI assistants like Claude to directly view and analyze your GIMP images!

Key Features

✨ MCP-Compliant Image Export: Direct image viewing for AI assistants
🎨 Full GIMP 3.0 API Access: Execute any GIMP operation via PyGObject
🔧 Multi-Format Export: PNG, JPEG, BMP, TIFF with quality control
📊 Image Metadata: Get image info without transferring data
🛡️ Robust Error Handling: Multiple fallback methods for reliability
🔌 Universal MCP Support: Works with Claude Desktop, Gemini CLI, PydanticAI, and more

Prerequisites

• GIMP 3.0 and above: This project is developed and tested with GIMP 3.0. Earlier versions are not supported.
• MCP-compatible AI client: Claude Desktop, Gemini CLI, PydanticAI, or other MCP clients.
• Python 3.8+: Required for the MCP server.
• uv: A modern Python package installer and resolver.

Quick Start

1. Install Dependencies

# Clone the repository
git clone https://github.com/maorcc/gimp-mcp.git
cd gimp-mcp

# Install Python dependencies
uv sync

2. Install the GIMP Plugin

Copy the gimp-mcp-plugin.py to your GIMP plug-ins directory and make it executable.

Quick Install (Linux):

# For standard GIMP installation
mkdir -p ~/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin
cp gimp-mcp-plugin.py ~/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin/
chmod +x ~/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py

# For Snap-installed GIMP
mkdir -p ~/snap/gimp/current/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin
cp gimp-mcp-plugin.py ~/snap/gimp/current/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin/
chmod +x ~/snap/gimp/current/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py

Quick Install (macOS):

mkdir -p ~/Library/Application\ Support/GIMP/3.0/plug-ins/gimp-mcp-plugin
cp gimp-mcp-plugin.py ~/Library/Application\ Support/GIMP/3.0/plug-ins/gimp-mcp-plugin/
chmod +x ~/Library/Application\ Support/GIMP/3.0/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py

Manual Installation:

For detailed instructions on locating your GIMP plugins folder across different operating systems, please refer to this guide:

GIMP Plugin Installation Guide (Wikibooks)

Make sure the plugin file has "execute" permission.

Restart GIMP after installation.

3. Start the MCP Server in GIMP

1. Open any image in GIMP
2. Navigate to Tools > Start MCP Server
3. The server will start on localhost:9877

4. Configure Your MCP Client

Claude Desktop

Add these lines to your Claude Desktop configuration file:
Location: ~/.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"
      ]
    }
  }
}

Gemini CLI

Configure your Gemini CLI MCP server in ~/.config/gemini/.gemini_config.json:

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

PydanticAI

For PydanticAI agents, use the MCPServerStdio class:

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

server = MCPServerStdio(
    'uv',
    args=[
        'run',
        '--directory',
        '/full/path/to/gimp-mcp',
        'gimp_mcp_server.py'
    ]
)

agent = Agent('openai:gpt-4o', mcp_servers=[server])

Claude Code

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

Other MCP Clients

For other MCP clients that support stdio transport, use the command:

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

Usage Examples

Basic Usage

1. Start GIMP and open any image
2. Start MCP Server: Tools > Start MCP Server
3. Launch your MCP client (Claude Desktop, etc.)
4. Start creating: "Draw a face and a sheep with GIMP"

Advanced Features

Image Analysis

"Can you show me the current image in GIMP and tell me what you see?"

Uses get_image_bitmap() to retrieve and analyze the current canvas

Fast Image Information

"What are the dimensions and properties of the current image?"

Uses get_image_metadata() to quickly get image info without transferring bitmap data

Smart Workflow Decisions

"Check if the current image has transparency and multiple layers before applying the effect"

Uses get_image_metadata() to analyze image structure for intelligent decision making

Environment Discovery

"What version of GIMP am I working with and what features are available?"

Uses get_gimp_info() to provide comprehensive environment information for optimal support

Troubleshooting Support

"I'm having issues with plugin exports - check my GIMP setup and suggest solutions"

Uses get_gimp_info() to diagnose installation and configuration problems

Complex Workflows

"Create a new 800x600 image, draw a blue circle in the center, add a red border, then show me the result"

Combines multiple GIMP operations with image export for verification

Available MCP Tools

The GIMP MCP server provides several tools that AI assistants can use:

🖼️ Image Export Tools

• get_image_bitmap()

Returns the current image as a base64-encoded PNG bitmap with support for region extraction and scaling.

Parameters:

• max_width (optional): Maximum width for full image scaling
• max_height (optional): Maximum height for full image scaling
• region (optional): Dictionary for region extraction with keys:
  • origin_x: X coordinate of region top-left corner
  • origin_y: Y coordinate of region top-left corner
  • width: Width of region to extract
  • height: Height of region to extract
  • max_width: Maximum width for region scaling (optional)
  • max_height: Maximum height for region scaling (optional)

Usage Examples:

# Get full image bitmap
result = await client.get_image_bitmap()

# Get full image scaled to max 800x600 (preserves aspect ratio)
result = await client.get_image_bitmap(max_width=800, max_height=600)

# Extract a region (100,100) with size 400x300
result = await client.get_image_bitmap(
    region={"origin_x": 100, "origin_y": 100, "width": 400, "height": 300}
)

# Extract region and scale it to 200x150 (preserves aspect ratio)
result = await client.get_image_bitmap(
    region={
        "origin_x": 100, "origin_y": 100, "width": 400, "height": 300,
        "max_width": 200, "max_height": 150
    }
)

if result['status'] == 'success':
    image_data = result['results']['image_data']  # base64-encoded PNG
    width = result['results']['width']
    height = result['results']['height']
    original_width = result['results']['original_width']
    original_height = result['results']['original_height']
    processing = result['results']['processing_applied']

- **`get_image_metadata()`**: Get comprehensive image metadata without bitmap data (fast)

### 🔍 System Information Tools
- **`get_gimp_info()`**: Get comprehensive GIMP installation and environment information
- **`get_context_state()`**: Get current GIMP context state (colors, brush, feathering, opacity)

Returns current GIMP context state including foreground/background colors, brush, opacity, paint mode, feather settings, and antialiasing state.

### 🔧 API Access Tool  
- **`call_api(api_path, args, kwargs)`**: Execute any GIMP 3.0 PyGObject command

### 🎨 Common Operations Available
- Create new images and layers
- Draw shapes, lines, and curves  
- Apply filters and effects
- Adjust colors and brightness
- Add text and selections
- Copy/paste between images
- Export in various formats

For detailed API documentation, see [GIMP_MCP_PROTOCOL.md](GIMP_MCP_PROTOCOL.md).

## Technical Architecture

### MCP Compliance
- **Image Content**: Returns proper `ImageContent` objects with base64 data and MIME types
- **Error Handling**: Uses MCP-standard exception propagation  
- **Tool Metadata**: Comprehensive tool descriptions and parameter schemas
- **Protocol Version**: Compatible with MCP specification 2025-06-18

### GIMP 3.0 Integration
- **PyGObject API**: Direct access to GIMP's Python bindings
- **Persistent Context**: Command execution maintains state between calls
- **Robust Export**: Multiple fallback methods for reliable image export
- **Real-time Updates**: Immediate display refresh with `Gimp.displays_flush()`

## Troubleshooting

### Common Issues

#### "Could not connect to GIMP"
- Ensure GIMP is running with an open image
- Verify the MCP Server is started (Tools > Start MCP Server)
- Check that port 9877 is not blocked by firewall

#### Export Errors
- The plugin includes multiple fallback export methods
- Supports various GIMP 3.0 API versions
- Automatically handles missing export procedures

#### Plugin Not Visible
- Verify plugin is in correct directory with execute permissions
- Restart GIMP after installation
- Check GIMP's error console for plugin loading issues

### Debug Mode
Add debug logging to see detailed MCP communication:
```bash
GIMP_MCP_DEBUG=1 uv run --directory /path/to/gimp-mcp gimp_mcp_server.py

Example Output

Example output from the prompt "draw me a face and a sheep" using GIMP MCP

Future Enhancements

We welcome contributions! Here are some areas for improvement:

Planned Features

• 📚 Recipe Collection: Common GIMP workflows as reusable MCP tools
• ↩️ Undo System: History management and rollback capabilities
• 🔍 Visual Feedback: Enhanced progress indicators and operation previews
• 🚀 Dynamic Discovery: Auto-generate MCP tools from GIMP's procedure database
• 📝 Enhanced Errors: Context-aware error messages with suggested fixes
• 🛡️ Resource Management: Better cleanup and error recovery in the plugin

Architecture Improvements

• 🔒 Security: Sandboxed execution environment for user commands
• ⚡ Performance: Optimized image transfer for large files
• 🌐 Remote Access: Support for network-accessible GIMP instances
• 📊 Analytics: Usage metrics and performance monitoring

Contributing

Contributions are welcome! Whether it's bug fixes, new features, or documentation improvements, feel free to submit a Pull Request or open an issue.