gimp-mcp-server 0.1.0
MCP Server for GIMP - AI Assistant for Image Editing
License: MIT
Requires Python: >=3.9
Keywords: mcp, gimp, ai, image-editing, graphics

# GIMP MCP Server

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Tests](https://img.shields.io/badge/tests-passing-green.svg)](#testing)
[![Documentation](https://img.shields.io/badge/docs-comprehensive-blue.svg)](docs/README.md)

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)

```bash
# 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](docs/user-guide/installation.md).

#### Linux (Ubuntu/Debian)
```bash
# 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)
```bash
# Install dependencies
brew install gimp python@3.9 gtk4 gobject-introspection
pip3 install PyGObject gimp-mcp-server
```

#### Windows
See [Windows Installation Guide](docs/user-guide/installation.md#windows-installation) for detailed setup instructions.

## 🎯 Quick Start

### 1. Start the Server

```bash
# 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`

```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
```javascript
// 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
```javascript
// 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
```bash
# 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
```bash
# 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
```bash
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
```bash
# 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](docs/user-guide/README.md)** - Installation, setup, and basic usage
- **[API Reference](docs/api-reference/README.md)** - Complete tool and resource documentation
- **[Tutorials](docs/tutorials/README.md)** - Step-by-step examples and workflows
- **[Integration Guide](docs/integration/README.md)** - MCP client integration
- **[Troubleshooting](docs/troubleshooting/README.md)** - Common issues and solutions

### Quick Reference
- **[Command Reference](docs/reference/commands.md)** - Quick tool reference
- **[Error Codes](docs/reference/error-codes.md)** - Error handling guide
- **[Parameter Reference](docs/reference/tool-parameters.md)** - Complete parameter guide

### Developer Resources
- **[Development Guide](docs/development/README.md)** - Contributing and development setup
- **[Architecture Guide](docs/architecture/README.md)** - Technical deep-dive
- **[Extension Guide](docs/extension/README.md)** - Adding new features
- **[Testing Guide](docs/testing/README.md)** - Testing procedures

## 🚨 Troubleshooting

### Common Issues

**GIMP Connection Failed**
```bash
# 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**
```bash
# 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**
```bash
# Linux: Add user to video group
sudo usermod -a -G video $USER

# Restart session after group changes
```

For detailed troubleshooting, see our [Troubleshooting Guide](docs/troubleshooting/README.md).

## 🚀 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](docs/development/README.md) 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
```bash
# 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](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](https://github.com/gimp-mcp/gimp-mcp-server/issues)
- **💬 Discussions**: [GitHub Discussions](https://github.com/gimp-mcp/gimp-mcp-server/discussions)
- **📖 Documentation**: [Complete Docs](docs/README.md)
- **🔄 Releases**: [Release Notes](https://github.com/gimp-mcp/gimp-mcp-server/releases)

---

**Made with ❤️ for the GIMP and AI community**