{"id":"9b1373d9-4d60-43eb-969c-377344f959ec","slug":"shotsan-gimp-mcp","kind":"mcp","name":"gimp-mcp","summary":"Control GIMP 3.x from AI via MCP + Script-Fu","owner":"shotsan","repoUrl":"https://github.com/shotsan/gimp-mcp","license":"GPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-05-30T04:31:50.000Z","addedAt":"2026-10-21T21:17:11.844Z","logoUrl":"https://avatars.githubusercontent.com/u/12378904?u=406055d973bbc727bfbbd1cdc37c03fb2d66bddc&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T12:40:14.485Z","sample":false,"url":"https://conduits.dev/tools/shotsan-gimp-mcp","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# gimp-mcp\n\nAI-powered control of GIMP 3.x through the Model Context Protocol (MCP).\n\nTalk to GIMP in natural language. Create images, apply filters, manipulate layers, draw shapes — all driven by an AI model through a standardized tool interface.\n\n## How it works\n\n```\n┌─────────────┐       stdio/MCP        ┌──────────────────┐      TCP:9876       ┌──────────────────┐\n│  AI Client  │ ◄──────────────────────► │  gimp_mcp_server │ ◄──────────────────► │  GIMP 3 Script-Fu│\n│  (mcp-cli,  │    JSON-RPC over stdin   │     (Python)     │   GIMP 3 protocol   │     Server       │\n│  Claude,    │    /stdout               │                  │   (binary framed)   │  (built-in)      │\n│  Cursor...) │                          │  16+ MCP tools   │                     │  900+ PDB procs  │\n└─────────────┘                          └──────────────────┘                     └──────────────────┘\n```\n\n**No plugin installation required.** Uses GIMP's built-in Script-Fu server directly.\n\nThe MCP server translates tool calls into Script-Fu (Scheme) expressions, sends them to GIMP over a TCP socket, and returns structured results. Any MCP-compatible AI client can drive GIMP.\n\n## Quick start\n\n### 1. Install the MCP package\n\n```bash\npip install \"mcp[cli]\"\n```\n\n### 2. Clone this repo\n\n```bash\ngit clone https://github.com/shotsan/gimp-mcp.git\ncd gimp-mcp\n```\n\n### 3. Start the Script-Fu server in GIMP\n\nOpen GIMP 3.x, then:\n\n**Filters → Script-Fu → Start Server...**\n\nLeave port at **9876**, click OK. You should see the server start in the terminal where GIMP was launched.\n\n### 4. Run with mcp-cli (or any MCP client)\n\n```bash\npip install mcp-cli\n\n# Example with DeepSeek on AWS Bedrock:\nOPENAI_API_KEY=$AWS_BEARER_TOKEN_BEDROCK \\\nOPENAI_API_BASE=\"https://bedrock-mantle.us-east-1.api.aws/v1\" \\\nmcp-cli chat \\\n  --config-file server_config.json \\\n  --provider openai_compatible \\\n  --model deepseek.v3.2 \\\n  --confirm-mode never \\\n  --attach gimp3_pdb_reference.md\n```\n\n## Integration with AI clients\n\n### mcp-cli (any model, any provider)\n\n```bash\nmcp-cli chat \\\n  --config-file server_config.json \\\n  --provider openai_compatible \\\n  --model <your-model>\n```\n\nSet `OPENAI_API_KEY` and `OPENAI_API_BASE` for your provider.\n\n### Claude Desktop\n\nEdit `~/.config/claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gimp\": {\n      \"command\": \"python3\",\n      \"args\": [\"/absolute/path/to/gimp_mcp_server.py\"]\n    }\n  }\n}\n```\n\n### Kiro\n\nAdd to `.kiro/settings/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gimp\": {\n      \"command\": \"python3\",\n      \"args\": [\"/absolute/path/to/gimp_mcp_server.py\"]\n    }\n  }\n}\n```\n\n### 5ire\n\nAdd the server in the MCP panel:\n- Command: `python3`\n- Args: `/absolute/path/to/gimp_mcp_server.py`\n\n### Any OpenAI-compatible API\n\nThe server speaks standard MCP over stdio. Point any MCP client at it:\n\n```json\n{\n  \"command\": \"python3\",\n  \"args\": [\"/path/to/gimp_mcp_server.py\"]\n}\n```\n\n## Available MCP tools\n\n| Tool | Description |\n|------|-------------|\n| `list_images` | List all open images |\n| `get_image_info` | Width, height, layers of an image |\n| `create_image` | New blank RGB image |\n| `load_image` | Open a file from disk |\n| `save_image` | Export to disk (format from extension) |\n| `flatten_image` | Merge all layers |\n| `resize_image` | Scale to new dimensions |\n| `crop_image` | Crop to rectangle |\n| `flip_image` | Horizontal/vertical flip |\n| `rotate_image` | 90°/180°/270° rotation |\n| `add_layer` | New transparent layer |\n| `delete_layer` | Remove a layer |\n| `set_foreground_color` | Set paint color |\n| `fill_active_drawable` | Fill with foreground color |\n| `brightness_contrast` | Adjust brightness/contrast |\n| `hue_saturation` | Adjust HSL |\n| `add_text` | Add text layer |\n| `run_scriptfu` | Execute ANY Script-Fu expression |\n\nThe `run_scriptfu` tool is a universal escape hatch — it can call any of GIMP's 900+ PDB procedures directly. The AI model uses `gimp3_pdb_reference.md` as a reference for correct procedure names.\n\n## Protocol details\n\nCommunication between the MCP server and GIMP uses the Script-Fu server binary protocol:\n\n**Request:**\n```\n'G' (1 byte) + length (uint16 big-endian) + script (utf-8)\n```\n\n**Response:**\n```\nmagic (1 byte) + error (1 byte, 0=success) + length (uint16 big-endian) + body (utf-8)\n```\n\nThe MCP server opens a new TCP connection per command (thread-safe, no connection state issues).\n\n## File structure\n\n```\ngimp-mcp/\n├── gimp_mcp_server.py       # MCP server (runs outside GIMP, talks to Script-Fu)\n├── gimp3_pdb_reference.md   # Complete PDB reference for AI models\n├── server_config.json       # mcp-cli configuration\n├── LICENSE\n└── README.md\n```\n\n## Extending\n\nTo add new capabilities, you have two choices:\n\n**1. Add a named MCP tool** (for common operations):\n\n```python\n@mcp.tool()\ndef sharpen_image(image_id: int, amount: float = 0.5) -> str:\n    \"\"\"Sharpen the active drawable.\"\"\"\n    d = _get_active_drawable(image_id)\n    sf(f'(gimp-drawable-brightness-contrast {d} 0.0 {amount})')\n    sf(\"(gimp-displays-flush)\")\n    return json.dumps({\"sharpened\": image_id})\n```\n\n**2. Use run_scriptfu** (for anything — the AI composes the script):\n\nThe model can call any GIMP procedure through `run_scriptfu`. Add procedures to `gimp3_pdb_reference.md` so the model knows about them.\n\n## Requirements\n\n- GIMP 3.0+ (tested on 3.2.4)\n- Python 3.10+\n- `mcp` package (`pip install \"mcp[cli]\"`)\n- An MCP-compatible AI client\n\n## Supported GIMP installations\n\n| Installation | Script-Fu server path | Notes |\n|---|---|---|\n| System package | Just works | GIMP from apt/dnf |\n| Flatpak | Just works | `flatpak run org.gimp.GIMP` |\n| AppImage | Just works | Download from gimp.org |\n| Snap | May need `--network` plug | Snap sandboxing |\n\nThe Script-Fu server binds to `localhost:9876` — no firewall or network config needed.\n\n## Troubleshooting\n\n**\"Cannot reach GIMP Script-Fu server\"**\n→ In GIMP: Filters → Script-Fu → Start Server... → OK\n\n**Model uses wrong procedure names**\n→ Attach `gimp3_pdb_reference.md` with `--attach` flag. Contains all verified GIMP 3 procedure names.\n\n**\"No tool calls but found tool output\" (400 error)**\n→ Conversation state corrupted. Exit chat (`Ctrl+C`) and restart. Use `--confirm-mode never` to prevent this.\n\n**Script-Fu returns \"#\\<EOF\\>\"**\n→ The Script-Fu server process is stale. Kill it, restart GIMP, start the server again.\n\n## License\n\nMIT\n"}