gimp-mcp-server 0.1.0

MCP Server for GIMP - AI Assistant for Image Editing

GIMP MCP Server

A comprehensive Model Context Protocol (MCP) server implementation for GIMP 3.0+, enabling AI assistants to perform sophisticated image editing operations through GIMP's GObject Introspection bindings.

🌟 Features

Core Capabilities

• 🎨 Document Management: Create, open, save, and export GIMP documents
• 🗂️ Layer Operations: Advanced layer management with opacity, blend modes, and transformations
• ✏️ Drawing Tools: Brush strokes, shapes, and artistic drawing operations
• 🔲 Selection Tools: Rectangular, elliptical, and advanced selection management
• 🎨 Color Management: Color sampling, palette operations, and color space handling
• 🎭 Filter Operations: Image filters and effects processing
• 🔄 Hybrid Mode Support: Seamless operation in both GUI and headless environments
• 📡 Real-time Resources: Live document state and system status monitoring

Advanced Features

• ⚡ High Performance: Optimized for both single operations and batch processing
• 🛡️ Robust Error Handling: Comprehensive error management and recovery
• 🔧 Extensible Architecture: Modular design for easy feature additions
• 📊 Resource Monitoring: Real-time document and system state tracking
• 🔍 Comprehensive Logging: Detailed operation tracking and debugging

📋 Requirements

System Requirements

• Operating System: Linux (Ubuntu 20.04+), Windows 10+, macOS 11+
• Python: 3.9+ (for GIMP 3.0 compatibility)
• GIMP: 3.0+ with Python support enabled
• Memory: 4GB RAM minimum, 8GB recommended for large images
• Storage: 1GB free space for installation

Dependencies

• GTK4: GTK4 development libraries
• GObject: GObject Introspection libraries
• PyGObject: Python GObject bindings
• FastMCP: MCP server framework

🚀 Installation

Quick Install (Recommended)

# Install from PyPI (when available)
pip install gimp-mcp-server

# Or install from source
pip install git+https://github.com/gimp-mcp/gimp-mcp-server.git

Detailed Installation

For detailed installation instructions including platform-specific setup, see our Installation Guide.

Linux (Ubuntu/Debian)

# Install system dependencies
sudo apt update
sudo apt install gimp-3.0 python3-dev python3-pip
sudo apt install libgtk-4-dev libgirepository1.0-dev

# Install Python dependencies
pip3 install PyGObject
pip3 install gimp-mcp-server

macOS (Homebrew)

# Install dependencies
brew install gimp python@3.9 gtk4 gobject-introspection
pip3 install PyGObject gimp-mcp-server

Windows

See Windows Installation Guide for detailed setup instructions.

🎯 Quick Start

1. Start the Server

# Basic startup
gimp-mcp-server

# With custom configuration
gimp-mcp-server --port 3000 --host localhost --debug

2. Connect with Claude Desktop

Add to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "gimp": {
      "command": "gimp-mcp-server",
      "args": []
    }
  }
}

3. Test the Connection

In Claude Desktop, try:

"Create a new 1920x1080 document and add a red circle in the center"

Claude will automatically:

1. Create the document using create_document
2. Draw the circle using draw_ellipse
3. Set appropriate colors and layers

🏗️ Architecture

The GIMP MCP Server follows a modern, modular architecture:

src/gimp_mcp/
├── server.py              # FastMCP server implementation
├── gimp_api.py            # GIMP GI bindings wrapper
├── mode_manager.py        # GUI/Headless mode detection
├── tools/                 # MCP tool implementations
│   ├── document_tools.py  # Document management
│   ├── layer_tools.py     # Layer operations
│   ├── drawing_tools.py   # Drawing operations
│   ├── selection_tools.py # Selection management
│   ├── color_tools.py     # Color operations
│   └── filter_tools.py    # Filter operations
├── resources/             # MCP resource providers
│   └── providers.py       # Real-time state resources
└── utils/                 # Utility modules
    ├── logging.py         # Structured logging
    ├── errors.py          # Error handling
    ├── gi_helpers.py      # GObject helpers
    └── image_utils.py     # Image processing

🛠️ Available Tools

Document Management (6 tools)

Tool	Description	Key Parameters
create_document	Create new documents	width, height, resolution, color_mode
open_document	Open existing files	file_path
save_document	Save documents	document_id, file_path
export_document	Export to formats	file_path, format, options
get_document_info	Get document details	document_id
list_documents	List open documents	None

Layer Operations (8 tools)

Tool	Description	Key Parameters
create_layer	Create new layers	name, layer_type, opacity, blend_mode
get_layer_info	Get layer details	layer_id, document_id
set_layer_opacity	Adjust opacity	layer_id, opacity
set_layer_blend_mode	Change blend mode	layer_id, blend_mode
set_layer_visibility	Toggle visibility	layer_id, visible
duplicate_layer	Duplicate layers	layer_id, new_name
delete_layer	Remove layers	layer_id
move_layer	Reorder layers	layer_id, new_position

Drawing Tools (4 tools)

Tool	Description	Key Parameters
apply_brush_stroke	Paint with brushes	points, brush_name, size, color
draw_rectangle	Draw rectangles	x, y, width, height, fill_color
draw_ellipse	Draw ellipses	center_x, center_y, radius_x, radius_y
bucket_fill	Fill areas	x, y, color, threshold

Selection Tools (4 tools)

Tool	Description	Key Parameters
create_rectangular_selection	Rectangle selections	x, y, width, height
create_elliptical_selection	Ellipse selections	center_x, center_y, radius_x, radius_y
modify_selection	Modify selections	operation, value
clear_selection	Clear selections	None

Color Management (4 tools)

Tool	Description	Key Parameters
set_foreground_color	Set foreground	color
set_background_color	Set background	color
sample_color	Sample from image	x, y, sample_merged
get_active_palette	Get color palette	None

Filter Operations (3 tools)

Tool	Description	Key Parameters
apply_blur	Blur effects	radius, method
apply_sharpen	Sharpen effects	amount, threshold
adjust_brightness_contrast	Adjust levels	brightness, contrast

📡 Available Resources

Real-time State Monitoring

• document://current - Current document state
• document://list - List of open documents
• document://metadata - Document metadata
• system://status - System and server status
• system://capabilities - Server capabilities
• system://health - System health information
• palettes://active - Active color palette
• brushes://list - Available brush presets
• tools://current - Current tool state

💡 Example Usage

Basic Image Creation

// Create a new document
const doc = await mcp.callTool("create_document", {
  width: 1024,
  height: 768,
  name: "My Artwork"
});

// Create a layer for shapes
const layer = await mcp.callTool("create_layer", {
  name: "Shapes",
  layer_type: "RGB"
});

// Draw a blue rectangle
await mcp.callTool("draw_rectangle", {
  x: 100,
  y: 100,
  width: 300,
  height: 200,
  fill_color: "#3498DB"
});

// Add a red circle
await mcp.callTool("draw_ellipse", {
  center_x: 250,
  center_y: 200,
  radius_x: 80,
  radius_y: 80,
  fill_color: "#E74C3C"
});

// Save the document
await mcp.callTool("save_document", {
  file_path: "/path/to/my-artwork.xcf"
});

// Export as PNG
await mcp.callTool("export_document", {
  file_path: "/path/to/my-artwork.png",
  options: { optimize: true }
});

Batch Processing

// Process multiple images
const images = ["image1.jpg", "image2.jpg", "image3.jpg"];

for (const imagePath of images) {
  // Open image
  const doc = await mcp.callTool("open_document", {
    file_path: imagePath
  });
  
  // Apply blur filter
  await mcp.callTool("apply_blur", {
    radius: 2.0,
    method: "gaussian"
  });
  
  // Adjust brightness
  await mcp.callTool("adjust_brightness_contrast", {
    brightness: 10,
    contrast: 5
  });
  
  // Export processed version
  await mcp.callTool("export_document", {
    file_path: imagePath.replace(".jpg", "_processed.png")
  });
}

🧪 Testing

Run Tests

# Install test dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage
pytest --cov=gimp_mcp --cov-report=html

# Run specific test categories
pytest -m unit          # Unit tests only
pytest -m integration   # Integration tests only
pytest -m "not slow"    # Exclude slow tests

Test Server Connection

# Quick connection test
gimp-mcp-server --test-connection

# System requirements check
gimp-mcp-server --system-check

# Run in debug mode
GIMP_MCP_DEBUG=1 gimp-mcp-server --debug

🔧 Configuration

Environment Variables

export GIMP_MCP_DEBUG=1          # Enable debug logging
export GIMP_MCP_HOST=localhost   # Server host
export GIMP_MCP_PORT=3000        # Server port
export GIMP_MCP_MODE=hybrid      # Mode: gui, headless, or hybrid
export GIMP_MCP_LOG_LEVEL=INFO   # Logging level

Advanced Configuration

# Custom GIMP path
export GIMP_PATH=/custom/path/to/gimp

# Memory settings
export GIMP_CACHE_SIZE=4096      # 4GB cache
export GIMP_TILE_CACHE_SIZE=2048 # 2GB tiles

# Performance tuning
export GIMP_NUM_PROCESSORS=4     # CPU cores to use
export GIMP_USE_OPENCL=yes       # GPU acceleration

📖 Documentation

Comprehensive Docs

• User Guide - Installation, setup, and basic usage
• API Reference - Complete tool and resource documentation
• Tutorials - Step-by-step examples and workflows
• Integration Guide - MCP client integration
• Troubleshooting - Common issues and solutions

Quick Reference

• Command Reference - Quick tool reference
• Error Codes - Error handling guide
• Parameter Reference - Complete parameter guide

Developer Resources

• Development Guide - Contributing and development setup
• Architecture Guide - Technical deep-dive
• Extension Guide - Adding new features
• Testing Guide - Testing procedures

🚨 Troubleshooting

Common Issues

GIMP Connection Failed

# Check GIMP installation
which gimp && gimp --version

# Test GIMP Python support
gimp --batch-interpreter=python-fu-eval --batch='print("Python OK")' --batch='quit()'

# Install missing dependencies
pip install PyGObject

Module Import Errors

# Install system dependencies (Ubuntu)
sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-4.0

# Install system dependencies (macOS)
brew install pygobject3 gtk+3

Permission Errors

# Linux: Add user to video group
sudo usermod -a -G video $USER

# Restart session after group changes

For detailed troubleshooting, see our Troubleshooting Guide.

🚀 Performance

Optimization Tips

1. Use appropriate image sizes - Larger images consume more memory and processing time
2. Batch related operations - Group similar operations together
3. Monitor system resources - Close unused documents to free memory
4. Use headless mode - For batch processing without GUI overhead
5. Enable GPU acceleration - Set GIMP_USE_OPENCL=yes for compatible operations

Benchmarks

• Document creation: ~50ms for standard sizes (1920x1080)
• Layer operations: ~10-30ms depending on complexity
• Drawing operations: ~20-100ms depending on brush size and stroke length
• Filter operations: ~100ms-5s depending on filter type and image size

🤝 Contributing

We welcome contributions! Please see our Development Guide for details.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-tool
3. Make your changes with tests
4. Run the test suite: pytest
5. Submit a pull request

Development Setup

# Clone and setup
git clone https://github.com/gimp-mcp/gimp-mcp-server.git
cd gimp-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

📊 Project Status

Current Status

• ✅ Core Implementation: Complete with all major tools
• ✅ Documentation: Comprehensive user and developer docs
• ✅ Testing: Full test suite with unit and integration tests
• ✅ Error Handling: Robust error management and recovery
• ✅ Performance: Optimized for production use
• 🔄 PyPI Release: Coming soon
• 🔄 GUI Integration: Enhanced GUI mode features

Roadmap

• v1.1: Enhanced filter operations and batch processing
• v1.2: Plugin system for custom tools
• v1.3: Advanced selection tools and path operations
• v2.0: GIMP 3.1+ support and new features

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• GIMP Development Team - For excellent GObject Introspection bindings
• FastMCP Framework - For robust MCP server implementation
• Model Context Protocol - For standardized AI tool integration
• Community Contributors - For testing, feedback, and contributions

📞 Support & Community

• 📋 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: Complete Docs
• 🔄 Releases: Release Notes

---

Made with ❤️ for the GIMP and AI community