{"id":"c3d59380-67b8-4678-8be1-f6e5e1e80757","slug":"shriinivas-gimpmcp","kind":"mcp","name":"gimpmcp","summary":"GIMP MCP Server - Control GIMP through AI assistants using Model Context Protocol","owner":"Shriinivas","repoUrl":"https://github.com/Shriinivas/gimpmcp","license":"AGPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-09-30T09:22:44.000Z","addedAt":"2026-10-21T15:59:57.563Z","logoUrl":"https://avatars.githubusercontent.com/u/42069100?u=118f6de8c345144452857ebbe0cc2f8bcb87b6b8&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","memory-knowledge"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T13:08:01.636Z","sample":false,"url":"https://conduits.dev/tools/shriinivas-gimpmcp","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# GIMP MCP Server 🎨\n\n> **⚠️ Work in Progress**: This project is functional but still under active development. While the core features are working, thorough testing and additional functionality are being added. Expect changes and improvements in upcoming releases.\n\nA Model Context Protocol (MCP) server that enables live control of GIMP through natural language instructions. This allows AI assistants like Claude to directly manipulate images in real-time.\n\n## ✨ Features\n\n- 🎯 **Live Instance Control** - Direct manipulation of running GIMP documents\n- ⚡ **D-Bus Integration** - Real-time communication with GIMP 3\n- 🐍 **Python Code Execution** - Run arbitrary GIMP API code in live context\n- 📊 **Document Info** - Get image dimensions, layers, and properties\n- 📸 **Screenshot Support** - Visual feedback with viewport capture\n- 🔄 **Automatic Setup** - Virtual environment created on first run\n\n## 🖥️ Platform Support\n\n- **⚠️ Currently Linux Only** - Uses D-Bus which is Linux-specific\n- **Requires GIMP 3** - Uses new Python 3 plugin architecture with GObject Introspection\n\n## 🚀 Quick Start\n\n### 1. Install GIMP D-Bus Bridge Plugin\n\n1. Go to the [Releases page](https://github.com/Shriinivas/gimpmcp/releases)\n2. Download `gimpmcp-plugin.zip` from the latest release\n3. Extract to your GIMP plugins directory:\n   ```bash\n   cd ~/.config/GIMP/3.0/plug-ins/\n   unzip ~/Downloads/gimpmcp-plugin.zip\n   chmod +x gimpmcp/gimpmcp.py\n   chmod +x gimpmcp/gimpmcp/run_gimp_mcp.sh\n   ```\n\n### 2. Start GIMP and Enable D-Bus Service\n\n1. Launch GIMP:\n   ```bash\n   gimp\n   ```\n\n2. Enable MCP D-Bus service in GIMP:\n   - Go to: **Filters > Development > MCP D-Bus - Start**\n   - ✅ The service will remain active until you close GIMP\n   - You only need to do this once per GIMP session\n\n### 3. Connect with AI Tools\n\n**Auto-Setup**: The first time an AI client connects, it will automatically:\n- Create Python virtual environment in `gimpmcp/venv/`\n- Install all required dependencies from `requirements.txt`\n- Start the MCP server\n\nNo manual setup required!\n\n#### Claude Code\n\nEdit your Claude configuration file (`~/.claude.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"gimp-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"/path/to/gimpmcp/gimpmcp/run_gimp_mcp.sh\",\n      \"args\": [],\n      \"env\": {}\n    }\n  }\n}\n```\n\n#### Anthropic Claude Desktop\n\nUpdate Claude desktop app settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"gimp-mcp\": {\n      \"command\": \"/path/to/gimpmcp/gimpmcp/run_gimp_mcp.sh\"\n    }\n  }\n}\n```\n\n#### Google Gemini/Codex\n\nFor Gemini, edit settings file (`~/.gemini/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"gimp-mcp\": {\n      \"command\": \"/path/to/gimpmcp/gimpmcp/run_gimp_mcp.sh\"\n    }\n  }\n}\n```\n\nFor Codex, edit configuration (`~/.codex/config.toml`):\n\n```toml\n[mcp_servers.gimp-mcp]\ncommand = \"/path/to/gimpmcp/gimpmcp/run_gimp_mcp.sh\"\n```\n\n## 📚 Usage\n\n### With AI Assistants\n\nOnce configured, you can use natural language to control GIMP:\n\n```\nCreate a new 800x600 image with a red circle in the center\n```\n\n```\nGet information about the current document\n```\n\n```\nTake a screenshot of the current viewport\n```\n\n### Manual Testing with CLI\n\nThe client can also be used directly for manual testing:\n\n```bash\n# Get document info\npython gimpmcp_client.py get-info \"\"\n\n# Get viewport screenshot\npython gimpmcp_client.py get-viewport-screenshot \"format=png max_size=400\"\n\n# Execute Python code\npython gimpmcp_client.py execute-code \"code='print(\\\"Hello GIMP\\\")'\"\n\n# Execute code from file\npython gimpmcp_client.py execute-code -f my_script.py\n\n# Get structured JSON output\npython gimpmcp_client.py get-info \"\" --parse-out --pretty\n```\n\n## 🏗️ Architecture\n\nThe GIMP MCP follows a clean architecture pattern:\n\n```\nAI Client → MCP Server → CLI Client → D-Bus → GIMP Plugin → Live Document\n```\n\n- **`gimpmcp.py`**: GIMP 3 plugin that exposes D-Bus interface\n- **`gimpmcp/gimp_mcp_server.py`**: MCP server with tool definitions and docstrings for AI\n- **`gimpmcp/gimpmcp_client.py`**: Client that handles all command logic (used by both server and manual testing)\n- **`gimpmcp/run_gimp_mcp.sh`**: Wrapper script for automatic venv setup\n\n**Key Design**: No code duplication! The server simply wraps client functions with MCP tool decorators. The same code runs for both AI assistant usage and manual CLI testing.\n\n## 🎨 Available Context in Code Execution\n\nWhen your code executes in GIMP, you have access to:\n\n- `Gimp` - Main GIMP module (gi.repository.Gimp)\n- `GimpUi` - GIMP UI module\n- `Gegl` - GEGL image processing library\n- `GObject`, `Gio`, `GLib` - GTK/GNOME libraries\n- `image` - The active GIMP image object\n- `drawables` - List of selected drawables\n- `pdb` - GIMP Procedural Database (Gimp.get_pdb())\n\n## 💡 Examples\n\n### Layer Operations\n\n```python\n# Get active layer\nlayer = image.get_active_layer()\nprint(f\"Active layer: {layer.get_name() if layer else 'None'}\")\n\n# Create new layer\nnew_layer = Gimp.Layer.new(\n    image,\n    \"AI Generated Layer\",\n    image.get_width(),\n    image.get_height(),\n    Gimp.ImageType.RGBA_IMAGE,\n    100.0,\n    Gimp.LayerMode.NORMAL\n)\nimage.insert_layer(new_layer, None, 0)\n\n# Set layer opacity\nlayer.set_opacity(50.0)\n```\n\n### Using Procedural Database\n\n```python\n# Invert colors\nprocedure = pdb.lookup_procedure(\"gimp-drawable-invert\")\nconfig = procedure.create_config()\nconfig.set_property(\"drawable\", image.get_active_layer())\nprocedure.run(config)\n\n# Apply Gaussian blur\nprocedure = pdb.lookup_procedure(\"plug-in-gauss\")\nconfig = procedure.create_config()\nconfig.set_property(\"run-mode\", Gimp.RunMode.NONINTERACTIVE)\nconfig.set_property(\"image\", image)\nconfig.set_property(\"drawable\", image.get_active_layer())\nconfig.set_property(\"horizontal\", 5.0)\nconfig.set_property(\"vertical\", 5.0)\nprocedure.run(config)\n```\n\n### Selections and Filling\n\n```python\n# Create rectangular selection\nimage.select_rectangle(Gimp.ChannelOps.REPLACE, 100, 100, 300, 200)\n\n# Set foreground color\nGimp.context_set_foreground(Gegl.Color.new(\"red\"))\n\n# Fill selection\nlayer = image.get_active_layer()\nprocedure = pdb.lookup_procedure(\"gimp-drawable-edit-fill\")\nconfig = procedure.create_config()\nconfig.set_property(\"drawable\", layer)\nconfig.set_property(\"fill-type\", Gimp.FillType.FOREGROUND)\nprocedure.run(config)\n\n# Remove selection using PDB\nprocedure = pdb.lookup_procedure(\"gimp-selection-none\")\nconfig = procedure.create_config()\nconfig.set_property(\"image\", image)\nprocedure.run(config)\n\n# Update display\nGimp.displays_flush()\n```\n\n### Image Information\n\n```python\n# Get image dimensions\nwidth = image.get_width()\nheight = image.get_height()\nprint(f\"Image size: {width}x{height}\")\n\n# List all layers\nlayers = image.get_layers()\nfor layer in layers:\n    print(f\"Layer: {layer.get_name()}\")\n```\n\n## 🔧 How It Works\n\n1. **MCP Server receives request** - AI client sends command\n2. **Server calls client function** - Uses shared `execute_gimp_command()` from client\n3. **Client builds code** - Generates Python code for the command\n4. **D-Bus call** - Client calls D-Bus method `ExecuteCode` on `org.gimp.mcp.Bridge`\n5. **Plugin receives request** - GIMP plugin handles D-Bus method call\n6. **Execute in GIMP** - Code executes with full GIMP API access\n7. **Return response** - Plugin returns result via D-Bus\n8. **Format and return** - Server formats response for AI client\n\n## 🎯 D-Bus Service Details\n\n- **Service Name**: `org.gimp.mcp.Bridge`\n- **Object Path**: `/org/gimp/mcp/Bridge`\n- **Interface**: `org.gimp.mcp.Bridge`\n- **Method**: `ExecuteCode(code: str) -> str` (returns JSON)\n\n### Test D-Bus service directly:\n\n```bash\n# Check if service is running\ngdbus introspect --session --dest org.gimp.mcp.Bridge --object-path /org/gimp/mcp/Bridge\n\n# List registered services\ngdbus list | grep org.gimp.mcp.Bridge\n\n# Execute code\ngdbus call --session --dest org.gimp.mcp.Bridge --object-path /org/gimp/mcp/Bridge --method org.gimp.mcp.Bridge.ExecuteCode 'print(\"Hello GIMP\")'\n```\n\n## 🐛 Troubleshooting\n\n### Service not available\n- ✅ Make sure GIMP is running\n- ✅ Enable MCP D-Bus service: **Filters > Development > MCP D-Bus - Start**\n- ✅ Check service is registered: `gdbus list | grep org.gimp.mcp.Bridge`\n\n### D-Bus connection errors in sandboxed environments\nThe `run_gimp_mcp.sh` script automatically sets required environment variables:\n- `XDG_RUNTIME_DIR`\n- `DBUS_SESSION_BUS_ADDRESS`\n\n### Plugin not appearing in menu\n- Check that folder name and file name match: `gimpmcp/gimpmcp.py`\n- Make sure the file is executable: `chmod +x gimpmcp/gimpmcp.py`\n- Restart GIMP\n\n## 📖 GIMP 3 API Resources\n\n- [GIMP 3.0 API Reference](https://developer.gimp.org/api/3.0/)\n- [Python Plugin Tutorial](https://developer.gimp.org/resource/writing-a-plug-in/tutorial-python/)\n- [GObject Introspection](https://gi.readthedocs.io/en/latest/)\n\n## 📝 License\n\n[GPL-3.0](LICENSE)\n\n"}