# GIMP MCP Server
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
[](#testing)
[](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**
Raw data
{
"_id": null,
"home_page": null,
"name": "gimp-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "mcp, gimp, ai, image-editing, graphics",
"author": null,
"author_email": "GIMP MCP Server Team <support@gimp-mcp.com>",
"download_url": "https://files.pythonhosted.org/packages/20/dd/5bbe580bce9f29fb526d17d07dea9300227f038d8971cd2fc9db067f525f/gimp_mcp_server-0.1.0.tar.gz",
"platform": null,
"description": "# GIMP MCP Server\r\n\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://github.com/psf/black)\r\n[](#testing)\r\n[](docs/README.md)\r\n\r\nA 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.\r\n\r\n## \ud83c\udf1f Features\r\n\r\n### Core Capabilities\r\n- **\ud83c\udfa8 Document Management**: Create, open, save, and export GIMP documents\r\n- **\ud83d\uddc2\ufe0f Layer Operations**: Advanced layer management with opacity, blend modes, and transformations\r\n- **\u270f\ufe0f Drawing Tools**: Brush strokes, shapes, and artistic drawing operations\r\n- **\ud83d\udd32 Selection Tools**: Rectangular, elliptical, and advanced selection management\r\n- **\ud83c\udfa8 Color Management**: Color sampling, palette operations, and color space handling\r\n- **\ud83c\udfad Filter Operations**: Image filters and effects processing\r\n- **\ud83d\udd04 Hybrid Mode Support**: Seamless operation in both GUI and headless environments\r\n- **\ud83d\udce1 Real-time Resources**: Live document state and system status monitoring\r\n\r\n### Advanced Features\r\n- **\u26a1 High Performance**: Optimized for both single operations and batch processing\r\n- **\ud83d\udee1\ufe0f Robust Error Handling**: Comprehensive error management and recovery\r\n- **\ud83d\udd27 Extensible Architecture**: Modular design for easy feature additions\r\n- **\ud83d\udcca Resource Monitoring**: Real-time document and system state tracking\r\n- **\ud83d\udd0d Comprehensive Logging**: Detailed operation tracking and debugging\r\n\r\n## \ud83d\udccb Requirements\r\n\r\n### System Requirements\r\n- **Operating System**: Linux (Ubuntu 20.04+), Windows 10+, macOS 11+\r\n- **Python**: 3.9+ (for GIMP 3.0 compatibility)\r\n- **GIMP**: 3.0+ with Python support enabled\r\n- **Memory**: 4GB RAM minimum, 8GB recommended for large images\r\n- **Storage**: 1GB free space for installation\r\n\r\n### Dependencies\r\n- **GTK4**: GTK4 development libraries\r\n- **GObject**: GObject Introspection libraries\r\n- **PyGObject**: Python GObject bindings\r\n- **FastMCP**: MCP server framework\r\n\r\n## \ud83d\ude80 Installation\r\n\r\n### Quick Install (Recommended)\r\n\r\n```bash\r\n# Install from PyPI (when available)\r\npip install gimp-mcp-server\r\n\r\n# Or install from source\r\npip install git+https://github.com/gimp-mcp/gimp-mcp-server.git\r\n```\r\n\r\n### Detailed Installation\r\n\r\nFor detailed installation instructions including platform-specific setup, see our [Installation Guide](docs/user-guide/installation.md).\r\n\r\n#### Linux (Ubuntu/Debian)\r\n```bash\r\n# Install system dependencies\r\nsudo apt update\r\nsudo apt install gimp-3.0 python3-dev python3-pip\r\nsudo apt install libgtk-4-dev libgirepository1.0-dev\r\n\r\n# Install Python dependencies\r\npip3 install PyGObject\r\npip3 install gimp-mcp-server\r\n```\r\n\r\n#### macOS (Homebrew)\r\n```bash\r\n# Install dependencies\r\nbrew install gimp python@3.9 gtk4 gobject-introspection\r\npip3 install PyGObject gimp-mcp-server\r\n```\r\n\r\n#### Windows\r\nSee [Windows Installation Guide](docs/user-guide/installation.md#windows-installation) for detailed setup instructions.\r\n\r\n## \ud83c\udfaf Quick Start\r\n\r\n### 1. Start the Server\r\n\r\n```bash\r\n# Basic startup\r\ngimp-mcp-server\r\n\r\n# With custom configuration\r\ngimp-mcp-server --port 3000 --host localhost --debug\r\n```\r\n\r\n### 2. Connect with Claude Desktop\r\n\r\nAdd to your Claude Desktop configuration file:\r\n\r\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json` \r\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` \r\n**Linux**: `~/.config/claude/claude_desktop_config.json`\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"gimp\": {\r\n \"command\": \"gimp-mcp-server\",\r\n \"args\": []\r\n }\r\n }\r\n}\r\n```\r\n\r\n### 3. Test the Connection\r\n\r\nIn Claude Desktop, try:\r\n> \"Create a new 1920x1080 document and add a red circle in the center\"\r\n\r\nClaude will automatically:\r\n1. Create the document using `create_document`\r\n2. Draw the circle using `draw_ellipse`\r\n3. Set appropriate colors and layers\r\n\r\n## \ud83c\udfd7\ufe0f Architecture\r\n\r\nThe GIMP MCP Server follows a modern, modular architecture:\r\n\r\n```\r\nsrc/gimp_mcp/\r\n\u251c\u2500\u2500 server.py # FastMCP server implementation\r\n\u251c\u2500\u2500 gimp_api.py # GIMP GI bindings wrapper\r\n\u251c\u2500\u2500 mode_manager.py # GUI/Headless mode detection\r\n\u251c\u2500\u2500 tools/ # MCP tool implementations\r\n\u2502 \u251c\u2500\u2500 document_tools.py # Document management\r\n\u2502 \u251c\u2500\u2500 layer_tools.py # Layer operations\r\n\u2502 \u251c\u2500\u2500 drawing_tools.py # Drawing operations\r\n\u2502 \u251c\u2500\u2500 selection_tools.py # Selection management\r\n\u2502 \u251c\u2500\u2500 color_tools.py # Color operations\r\n\u2502 \u2514\u2500\u2500 filter_tools.py # Filter operations\r\n\u251c\u2500\u2500 resources/ # MCP resource providers\r\n\u2502 \u2514\u2500\u2500 providers.py # Real-time state resources\r\n\u2514\u2500\u2500 utils/ # Utility modules\r\n \u251c\u2500\u2500 logging.py # Structured logging\r\n \u251c\u2500\u2500 errors.py # Error handling\r\n \u251c\u2500\u2500 gi_helpers.py # GObject helpers\r\n \u2514\u2500\u2500 image_utils.py # Image processing\r\n```\r\n\r\n## \ud83d\udee0\ufe0f Available Tools\r\n\r\n### Document Management (6 tools)\r\n| Tool | Description | Key Parameters |\r\n|------|-------------|----------------|\r\n| `create_document` | Create new documents | `width`, `height`, `resolution`, `color_mode` |\r\n| `open_document` | Open existing files | `file_path` |\r\n| `save_document` | Save documents | `document_id`, `file_path` |\r\n| `export_document` | Export to formats | `file_path`, `format`, `options` |\r\n| `get_document_info` | Get document details | `document_id` |\r\n| `list_documents` | List open documents | None |\r\n\r\n### Layer Operations (8 tools)\r\n| Tool | Description | Key Parameters |\r\n|------|-------------|----------------|\r\n| `create_layer` | Create new layers | `name`, `layer_type`, `opacity`, `blend_mode` |\r\n| `get_layer_info` | Get layer details | `layer_id`, `document_id` |\r\n| `set_layer_opacity` | Adjust opacity | `layer_id`, `opacity` |\r\n| `set_layer_blend_mode` | Change blend mode | `layer_id`, `blend_mode` |\r\n| `set_layer_visibility` | Toggle visibility | `layer_id`, `visible` |\r\n| `duplicate_layer` | Duplicate layers | `layer_id`, `new_name` |\r\n| `delete_layer` | Remove layers | `layer_id` |\r\n| `move_layer` | Reorder layers | `layer_id`, `new_position` |\r\n\r\n### Drawing Tools (4 tools)\r\n| Tool | Description | Key Parameters |\r\n|------|-------------|----------------|\r\n| `apply_brush_stroke` | Paint with brushes | `points`, `brush_name`, `size`, `color` |\r\n| `draw_rectangle` | Draw rectangles | `x`, `y`, `width`, `height`, `fill_color` |\r\n| `draw_ellipse` | Draw ellipses | `center_x`, `center_y`, `radius_x`, `radius_y` |\r\n| `bucket_fill` | Fill areas | `x`, `y`, `color`, `threshold` |\r\n\r\n### Selection Tools (4 tools)\r\n| Tool | Description | Key Parameters |\r\n|------|-------------|----------------|\r\n| `create_rectangular_selection` | Rectangle selections | `x`, `y`, `width`, `height` |\r\n| `create_elliptical_selection` | Ellipse selections | `center_x`, `center_y`, `radius_x`, `radius_y` |\r\n| `modify_selection` | Modify selections | `operation`, `value` |\r\n| `clear_selection` | Clear selections | None |\r\n\r\n### Color Management (4 tools)\r\n| Tool | Description | Key Parameters |\r\n|------|-------------|----------------|\r\n| `set_foreground_color` | Set foreground | `color` |\r\n| `set_background_color` | Set background | `color` |\r\n| `sample_color` | Sample from image | `x`, `y`, `sample_merged` |\r\n| `get_active_palette` | Get color palette | None |\r\n\r\n### Filter Operations (3 tools)\r\n| Tool | Description | Key Parameters |\r\n|------|-------------|----------------|\r\n| `apply_blur` | Blur effects | `radius`, `method` |\r\n| `apply_sharpen` | Sharpen effects | `amount`, `threshold` |\r\n| `adjust_brightness_contrast` | Adjust levels | `brightness`, `contrast` |\r\n\r\n## \ud83d\udce1 Available Resources\r\n\r\n### Real-time State Monitoring\r\n- `document://current` - Current document state\r\n- `document://list` - List of open documents \r\n- `document://metadata` - Document metadata\r\n- `system://status` - System and server status\r\n- `system://capabilities` - Server capabilities\r\n- `system://health` - System health information\r\n- `palettes://active` - Active color palette\r\n- `brushes://list` - Available brush presets\r\n- `tools://current` - Current tool state\r\n\r\n## \ud83d\udca1 Example Usage\r\n\r\n### Basic Image Creation\r\n```javascript\r\n// Create a new document\r\nconst doc = await mcp.callTool(\"create_document\", {\r\n width: 1024,\r\n height: 768,\r\n name: \"My Artwork\"\r\n});\r\n\r\n// Create a layer for shapes\r\nconst layer = await mcp.callTool(\"create_layer\", {\r\n name: \"Shapes\",\r\n layer_type: \"RGB\"\r\n});\r\n\r\n// Draw a blue rectangle\r\nawait mcp.callTool(\"draw_rectangle\", {\r\n x: 100,\r\n y: 100,\r\n width: 300,\r\n height: 200,\r\n fill_color: \"#3498DB\"\r\n});\r\n\r\n// Add a red circle\r\nawait mcp.callTool(\"draw_ellipse\", {\r\n center_x: 250,\r\n center_y: 200,\r\n radius_x: 80,\r\n radius_y: 80,\r\n fill_color: \"#E74C3C\"\r\n});\r\n\r\n// Save the document\r\nawait mcp.callTool(\"save_document\", {\r\n file_path: \"/path/to/my-artwork.xcf\"\r\n});\r\n\r\n// Export as PNG\r\nawait mcp.callTool(\"export_document\", {\r\n file_path: \"/path/to/my-artwork.png\",\r\n options: { optimize: true }\r\n});\r\n```\r\n\r\n### Batch Processing\r\n```javascript\r\n// Process multiple images\r\nconst images = [\"image1.jpg\", \"image2.jpg\", \"image3.jpg\"];\r\n\r\nfor (const imagePath of images) {\r\n // Open image\r\n const doc = await mcp.callTool(\"open_document\", {\r\n file_path: imagePath\r\n });\r\n \r\n // Apply blur filter\r\n await mcp.callTool(\"apply_blur\", {\r\n radius: 2.0,\r\n method: \"gaussian\"\r\n });\r\n \r\n // Adjust brightness\r\n await mcp.callTool(\"adjust_brightness_contrast\", {\r\n brightness: 10,\r\n contrast: 5\r\n });\r\n \r\n // Export processed version\r\n await mcp.callTool(\"export_document\", {\r\n file_path: imagePath.replace(\".jpg\", \"_processed.png\")\r\n });\r\n}\r\n```\r\n\r\n## \ud83e\uddea Testing\r\n\r\n### Run Tests\r\n```bash\r\n# Install test dependencies\r\npip install -e \".[dev]\"\r\n\r\n# Run all tests\r\npytest\r\n\r\n# Run with coverage\r\npytest --cov=gimp_mcp --cov-report=html\r\n\r\n# Run specific test categories\r\npytest -m unit # Unit tests only\r\npytest -m integration # Integration tests only\r\npytest -m \"not slow\" # Exclude slow tests\r\n```\r\n\r\n### Test Server Connection\r\n```bash\r\n# Quick connection test\r\ngimp-mcp-server --test-connection\r\n\r\n# System requirements check\r\ngimp-mcp-server --system-check\r\n\r\n# Run in debug mode\r\nGIMP_MCP_DEBUG=1 gimp-mcp-server --debug\r\n```\r\n\r\n## \ud83d\udd27 Configuration\r\n\r\n### Environment Variables\r\n```bash\r\nexport GIMP_MCP_DEBUG=1 # Enable debug logging\r\nexport GIMP_MCP_HOST=localhost # Server host\r\nexport GIMP_MCP_PORT=3000 # Server port\r\nexport GIMP_MCP_MODE=hybrid # Mode: gui, headless, or hybrid\r\nexport GIMP_MCP_LOG_LEVEL=INFO # Logging level\r\n```\r\n\r\n### Advanced Configuration\r\n```bash\r\n# Custom GIMP path\r\nexport GIMP_PATH=/custom/path/to/gimp\r\n\r\n# Memory settings\r\nexport GIMP_CACHE_SIZE=4096 # 4GB cache\r\nexport GIMP_TILE_CACHE_SIZE=2048 # 2GB tiles\r\n\r\n# Performance tuning\r\nexport GIMP_NUM_PROCESSORS=4 # CPU cores to use\r\nexport GIMP_USE_OPENCL=yes # GPU acceleration\r\n```\r\n\r\n## \ud83d\udcd6 Documentation\r\n\r\n### Comprehensive Docs\r\n- **[User Guide](docs/user-guide/README.md)** - Installation, setup, and basic usage\r\n- **[API Reference](docs/api-reference/README.md)** - Complete tool and resource documentation\r\n- **[Tutorials](docs/tutorials/README.md)** - Step-by-step examples and workflows\r\n- **[Integration Guide](docs/integration/README.md)** - MCP client integration\r\n- **[Troubleshooting](docs/troubleshooting/README.md)** - Common issues and solutions\r\n\r\n### Quick Reference\r\n- **[Command Reference](docs/reference/commands.md)** - Quick tool reference\r\n- **[Error Codes](docs/reference/error-codes.md)** - Error handling guide\r\n- **[Parameter Reference](docs/reference/tool-parameters.md)** - Complete parameter guide\r\n\r\n### Developer Resources\r\n- **[Development Guide](docs/development/README.md)** - Contributing and development setup\r\n- **[Architecture Guide](docs/architecture/README.md)** - Technical deep-dive\r\n- **[Extension Guide](docs/extension/README.md)** - Adding new features\r\n- **[Testing Guide](docs/testing/README.md)** - Testing procedures\r\n\r\n## \ud83d\udea8 Troubleshooting\r\n\r\n### Common Issues\r\n\r\n**GIMP Connection Failed**\r\n```bash\r\n# Check GIMP installation\r\nwhich gimp && gimp --version\r\n\r\n# Test GIMP Python support\r\ngimp --batch-interpreter=python-fu-eval --batch='print(\"Python OK\")' --batch='quit()'\r\n\r\n# Install missing dependencies\r\npip install PyGObject\r\n```\r\n\r\n**Module Import Errors**\r\n```bash\r\n# Install system dependencies (Ubuntu)\r\nsudo apt install python3-gi python3-gi-cairo gir1.2-gtk-4.0\r\n\r\n# Install system dependencies (macOS)\r\nbrew install pygobject3 gtk+3\r\n```\r\n\r\n**Permission Errors**\r\n```bash\r\n# Linux: Add user to video group\r\nsudo usermod -a -G video $USER\r\n\r\n# Restart session after group changes\r\n```\r\n\r\nFor detailed troubleshooting, see our [Troubleshooting Guide](docs/troubleshooting/README.md).\r\n\r\n## \ud83d\ude80 Performance\r\n\r\n### Optimization Tips\r\n1. **Use appropriate image sizes** - Larger images consume more memory and processing time\r\n2. **Batch related operations** - Group similar operations together\r\n3. **Monitor system resources** - Close unused documents to free memory\r\n4. **Use headless mode** - For batch processing without GUI overhead\r\n5. **Enable GPU acceleration** - Set `GIMP_USE_OPENCL=yes` for compatible operations\r\n\r\n### Benchmarks\r\n- **Document creation**: ~50ms for standard sizes (1920x1080)\r\n- **Layer operations**: ~10-30ms depending on complexity\r\n- **Drawing operations**: ~20-100ms depending on brush size and stroke length\r\n- **Filter operations**: ~100ms-5s depending on filter type and image size\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Please see our [Development Guide](docs/development/README.md) for details.\r\n\r\n### Quick Contribution Steps\r\n1. **Fork** the repository\r\n2. **Create** a feature branch: `git checkout -b feature/new-tool`\r\n3. **Make** your changes with tests\r\n4. **Run** the test suite: `pytest`\r\n5. **Submit** a pull request\r\n\r\n### Development Setup\r\n```bash\r\n# Clone and setup\r\ngit clone https://github.com/gimp-mcp/gimp-mcp-server.git\r\ncd gimp-mcp-server\r\n\r\n# Create virtual environment\r\npython -m venv venv\r\nsource venv/bin/activate # Windows: venv\\Scripts\\activate\r\n\r\n# Install in development mode\r\npip install -e \".[dev]\"\r\n\r\n# Install pre-commit hooks\r\npre-commit install\r\n\r\n# Run tests\r\npytest\r\n```\r\n\r\n## \ud83d\udcca Project Status\r\n\r\n### Current Status\r\n- \u2705 **Core Implementation**: Complete with all major tools\r\n- \u2705 **Documentation**: Comprehensive user and developer docs\r\n- \u2705 **Testing**: Full test suite with unit and integration tests\r\n- \u2705 **Error Handling**: Robust error management and recovery\r\n- \u2705 **Performance**: Optimized for production use\r\n- \ud83d\udd04 **PyPI Release**: Coming soon\r\n- \ud83d\udd04 **GUI Integration**: Enhanced GUI mode features\r\n\r\n### Roadmap\r\n- **v1.1**: Enhanced filter operations and batch processing\r\n- **v1.2**: Plugin system for custom tools\r\n- **v1.3**: Advanced selection tools and path operations\r\n- **v2.0**: GIMP 3.1+ support and new features\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- **GIMP Development Team** - For excellent GObject Introspection bindings\r\n- **FastMCP Framework** - For robust MCP server implementation\r\n- **Model Context Protocol** - For standardized AI tool integration\r\n- **Community Contributors** - For testing, feedback, and contributions\r\n\r\n## \ud83d\udcde Support & Community\r\n\r\n- **\ud83d\udccb Issues**: [GitHub Issues](https://github.com/gimp-mcp/gimp-mcp-server/issues)\r\n- **\ud83d\udcac Discussions**: [GitHub Discussions](https://github.com/gimp-mcp/gimp-mcp-server/discussions)\r\n- **\ud83d\udcd6 Documentation**: [Complete Docs](docs/README.md)\r\n- **\ud83d\udd04 Releases**: [Release Notes](https://github.com/gimp-mcp/gimp-mcp-server/releases)\r\n\r\n---\r\n\r\n**Made with \u2764\ufe0f for the GIMP and AI community**\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP Server for GIMP - AI Assistant for Image Editing",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/slliws/gimp-mcp-server/issues",
"Documentation": "https://github.com/slliws/gimp-mcp-server/blob/main/docs/README.md",
"Homepage": "https://github.com/slliws/gimp-mcp-server",
"Repository": "https://github.com/slliws/gimp-mcp-server"
},
"split_keywords": [
"mcp",
" gimp",
" ai",
" image-editing",
" graphics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ff3dbe4a1c3f37ad735a3ceeb3dca7a3f465ea502b282b028365d252cf39d212",
"md5": "67903f32301f7e31f6956386555d92fb",
"sha256": "cab5d7aaec343d394b2b1b45302b08bf481261aa806bf59207b938764e2bbf1c"
},
"downloads": -1,
"filename": "gimp_mcp_server-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "67903f32301f7e31f6956386555d92fb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 51305,
"upload_time": "2025-07-12T15:23:56",
"upload_time_iso_8601": "2025-07-12T15:23:56.032663Z",
"url": "https://files.pythonhosted.org/packages/ff/3d/be4a1c3f37ad735a3ceeb3dca7a3f465ea502b282b028365d252cf39d212/gimp_mcp_server-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "20dd5bbe580bce9f29fb526d17d07dea9300227f038d8971cd2fc9db067f525f",
"md5": "8d052ecbf49d06bf61b04b50fe2b0146",
"sha256": "1d55e4630af6104994b8c698a336f74649b9468a33b2d7d57142250d6891f270"
},
"downloads": -1,
"filename": "gimp_mcp_server-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8d052ecbf49d06bf61b04b50fe2b0146",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 227794,
"upload_time": "2025-07-12T15:23:57",
"upload_time_iso_8601": "2025-07-12T15:23:57.748961Z",
"url": "https://files.pythonhosted.org/packages/20/dd/5bbe580bce9f29fb526d17d07dea9300227f038d8971cd2fc9db067f525f/gimp_mcp_server-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 15:23:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "slliws",
"github_project": "gimp-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "fastmcp",
"specs": [
[
">=",
"0.1.0"
]
]
},
{
"name": "mcp",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "PyGObject",
"specs": [
[
">=",
"3.42.0"
]
]
},
{
"name": "Pillow",
"specs": [
[
">=",
"9.0.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "structlog",
"specs": [
[
">=",
"22.0.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
}
],
"lcname": "gimp-mcp-server"
}
JSON
