GIMP-MCP connects the GNU Image Manipulation Program (GIMP 3.x / 2.10+) with AI models using the Model Context Protocol (MCP). This integration enables AI assistants (such as Claude, Antigravity, Cursor, and custom MCP clients) to interact directly with GIMP: inspecting open canvases, creating layers, scaling images, applying GEGL filters, executing PDB procedures, and running custom Python scripts in real time.
- Full GIMP 3.x & 2.10+ Compatibility: Native support for GIMP 3.x GObject Introspection (
gi.repository.Gimp,Gegl,GLib,Gtk). - Interactive Control GUI: When started from GIMP's menu, a lightweight status window appears showing connection state, live activity logs, and a Stop button without blocking or freezing GIMP.
- Headless & Batch Support: Can also run headlessly in batch mode or automated workflows using
gimp-console. - 1000+ PDB Procedures: Execute any procedure from GIMP's Procedural Database with automatic type conversion for images, drawables, files, and colors.
- GEGL Filters: Apply filters such as Gaussian Blur, Pixelize, Sepia, and more directly to layers.
- Full Python Scripting: Execute arbitrary Python snippets inside GIMP's runtime for advanced compositing.
- Thread-Safe Architecture: All external socket calls are dispatched onto GIMP's main GLib event loop via
GLib.idle_add, preventing UI freezes and crashes.
- GIMP 3.0+ (tested on GIMP 3.2.6) or GIMP 2.10.
- Python 3.10+ with
PyGObjectinstalled. - Required Python dependencies:
pip install -r requirements.txt
Run the provided installation script:
python3 install.pyThe installer will:
- Detect your installed GIMP version (e.g. GIMP 3.2.6).
- Locate the user plug-ins directory (
~/.config/GIMP/3.2/plug-ins/). - Create the plugin directory structure (
gimp_mcp_server/gimp_mcp_server.py). - Set executable permissions and verify registration with GIMP.
To install as a symbolic link (convenient for development):
python3 install.py --link- Create a dedicated subdirectory in your GIMP 3 plug-ins folder:
mkdir -p ~/.config/GIMP/3.2/plug-ins/gimp_mcp_server - Copy
gimp_mcp_server.pyinto that directory:cp gimp_mcp_server.py ~/.config/GIMP/3.2/plug-ins/gimp_mcp_server/gimp_mcp_server.py chmod +x ~/.config/GIMP/3.2/plug-ins/gimp_mcp_server/gimp_mcp_server.py
- Restart GIMP.
- Open GIMP on your desktop.
- In the top menu, go to:
- Filters > Development > Start MCP Server
(or Tools > Start MCP Server)
- Filters > Development > Start MCP Server
- A small dialog will appear confirming:
GIMP MCP Server is active Listening on 127.0.0.1:9876 - You can keep this window open while working in GIMP. When finished, click Stop Server or close the window.
Run the FastMCP bridge process:
python3 gimp_mcp_client.pyBy default, it connects to 127.0.0.1:9876. You can customize the host or port using environment variables:
GIMP_MCP_PORT=9876 python3 gimp_mcp_client.pyAdd GIMP-MCP to your MCP client configuration (e.g., Claude Desktop claude_desktop_config.json or Antigravity MCP settings):
{
"mcpServers": {
"gimp": {
"command": "python3",
"args": ["/home/sugeng/Projects/Github/gimp-mcp/gimp_mcp_client.py"],
"env": {
"GIMP_MCP_PORT": "9876"
}
}
}
}| Tool | Description |
|---|---|
gimp_status |
Check if GIMP is connected, get GIMP version and open canvas count |
gimp_list_images |
List all open images with ID, width, height, and title |
gimp_get_image |
Inspect active or specific image details, dimensions, and layer tree |
gimp_create_image |
Create a new canvas with customizable dimensions and fill color |
gimp_list_layers |
List all layers in an image |
gimp_create_layer |
Add a new layer with custom dimensions, opacity, and blend mode |
gimp_set_layer_visibility |
Toggle visibility of any layer |
gimp_set_layer_opacity |
Adjust opacity (0.0 - 100.0) of a layer |
gimp_remove_layer |
Delete a layer from an image |
gimp_open_file |
Open an existing image file from disk |
gimp_save_image |
Save/export image to PNG, JPEG, TIFF, or XCF |
gimp_apply_filter |
Apply GEGL filters (e.g. gegl:gaussian-blur, gegl:sepia) |
gimp_execute_pdb |
Execute any of the 1,000+ GIMP Procedural Database (PDB) commands |
gimp_search_pdb |
Search available PDB procedures by keyword |
gimp_get_pdb_info |
Inspect procedure documentation, input arguments, and return types |
gimp_run_python |
Run arbitrary Python code directly inside GIMP's runtime environment |
gimp_refresh_display |
Force GIMP to redraw and flush display changes to screen |
+------------------------------------+ +----------------------------------------+
| AI Client | | GIMP |
| (Claude Desktop, Antigravity, etc) | | |
+-----------------+------------------+ | +----------------------------------+ |
| | | gimp_mcp_server Plugin | |
| MCP Protocol (stdio) | | (Filters > Dev > Start Server) | |
v | | | |
+------------------------------------+ | | +----------------------------+ | |
| gimp_mcp_client.py | | | | TCP Socket Server (:9876) | | |
| (FastMCP) | | | +-------------+--------------+ | |
+-----------------+------------------+ | +----------------|-----------------+ |
| | | |
| TCP Socket (JSON lines) | | GLib.idle_add |
+--------------------------->-------------------+ |
| v |
| GIMP Main UI & PDB Core |
| (Thread-Safe Execution) |
+----------------------------------------+
Contributions to GIMP-MCP are welcome! Whether you are fixing bugs, improving GIMP 3.x API coverage, adding new MCP tools, or updating documentation, here is how you can contribute:
-
Fork and clone the repository:
git clone https://github.com/<your-username>/gimp-mcp.git cd gimp-mcp
-
Install dependencies:
pip install -r requirements.txt
-
Install the plugin in development (symlink) mode: Using the
--linkflag links your working copy directly into GIMP's plug-ins directory so any code edits ingimp_mcp_server.pytake effect immediately without having to re-copy:python3 install.py --link
-
Test plug-in registration: Verify that GIMP indexes the plugin without errors:
gimp-console -c --batch-interpreter python-fu-eval -b "pass" --quit -
Run the FastMCP bridge:
python3 gimp_mcp_client.py
-
Verify socket communication: With GIMP running (or using
gimp-consolein batch mode), test sending commands to verify socket requests and PDB procedures return valid JSON.
-
Create a feature branch:
git checkout -b feature/your-feature-name
-
Commit your changes: Make sure commit messages are descriptive and concise:
git commit -m "Add feature: your feature description" -
Push to your fork:
git push origin feature/your-feature-name
-
Submit a Pull Request: Describe the problem you are solving, the changes made, and steps to test.
This project is licensed under the MIT License. See LICENSE for details.