Gimp Mcp

What is Gimp Mcp about?

Gimp Mcp provides a bridge between conversational AI clients (Claude Desktop, Gemini CLI, PydanticAI, etc.) and GIMP. By exposing the full GIMP API as MCP tools, users can describe desired image edits in plain language and have the system translate those requests into precise GIMP actions.

How to use Gimp Mcp?

1. Install the GIMP plugin – copy gimp-mcp-plugin.py into GIMP’s plug-ins folder and ensure it is executable.
2. Start the MCP server – inside GIMP, select Tools > Start MCP Server.
3. Configure your MCP client – add a server entry pointing to the project directory and run uv run --directory <path>/gimp-mcp-server server.py (examples provided for Claude Desktop, Gemini CLI, and PydanticAI).
4. Interact – send natural‑language prompts such as “brighten the background and add a vintage filter” to the AI client; the client will invoke the corresponding GIMP operations via MCP.

Key features of Gimp Mcp

• Full coverage of GIMP 3.0+ functionality through MCP tools.
• Compatibility with multiple MCP clients (Claude Desktop, Gemini CLI, PydanticAI, generic stdio clients).
• Simple plugin installation and server startup from within GIMP.
• Extensible recipe system for common workflows (planned).
• Designed for both non‑technical users (guided edits) and power users (complex multi‑step scripts).

Use cases of Gimp Mcp

• Rapid photo retouching – ask an AI to remove red‑eye, sharpen subjects, or adjust exposure without manual tool selection.
• Creative batch processing – define a sequence of edits (e.g., apply vintage filter, add watermark) and let the AI execute it on multiple images.
• Educational assistance – beginners can learn GIMP operations by seeing how natural‑language requests map to actual tool actions.
• Prototyping artistic concepts – quickly sketch ideas (“draw a face and a sheep”) and iterate via conversational feedback.

FAQ from the Gimp Mcp

• Do I need a specific GIMP version? Yes, GIMP 3.0 or newer is required.
• Can I use the server on Windows/macOS? The plugin works on all platforms; just place the file in the appropriate plug‑ins directory and give it execute permission.
• What if I use a different MCP client? As long as the client supports stdio transport, you can start the server with uv run --directory <path> server.py and point the client to it.
• Is there undo support? Currently not built‑in; an undo feature is listed in the improvement roadmap.
• How are errors reported? The server returns GIMP API error messages; future releases will enrich them with line numbers and suggested fixes.

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])

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.