mcp-gimp

Model Context Protocol server implementation for GIMP 3.

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio martinduartemore-mcp-gimp docker run -i martinduartemore/mcp-gimp-server:latest \
  --env DEBUG="true|false for verbose logs" \
  --env MCP_PORT="8080 (default MCP API port)" \
  --env GIMP_HOST="host or IP where GIMP bridge is accessible" \
  --env GIMP_PORT="5900 (VNC port for GIMP container, if applicable)"

How to use

The GIMP MCP server provides a bridge between external AI models or applications and a running GIMP instance. It exposes MCP-compliant endpoints to send commands, query GIMP objects (images, layers, paths, selections), and receive serialized representations suitable for agent reasoning. The system is designed to operate with GIMP 3 via the accompanying GIMP MCP Plugin, which executes commands received from the MCP server within a running GIMP session. External applications can register the MCP server and then issue commands to manipulate GIMP objects, run image processing tasks, and retrieve JSON-serialized representations of GIMP entities to feed back into AI workflows. The server is container-friendly, enabling quick prototyping in environments where GIMP runs inside a container with VNC-based access or in a remote setup.

How to install

Prerequisites:

Docker installed on your host or CI environment
Access to the repository containing the GIMP MCP Plugin and Server
Optional: docker-compose if you prefer orchestrating multiple containers

Installation steps:

Clone the repository: git clone https://github.com/martinduartemore/mcp-gimp.git cd mcp-gimp
Build or pull the GIMP MCP server image (if using Docker): docker pull martinduartemore/mcp-gimp-server:latest (or build locally if a Dockerfile is provided in the repo)
Run the MCP server container: docker run -d --name gimp-mcp-server -p 8080:8080 -e MCP_PORT=8080 martinduartemore/mcp-gimp-server:latest
If you also need the GIMP bridge plugin running, follow the repository's plugin installation guide for the GIMP MCP Plugin and ensure it connects to the MCP server endpoint (e.g., http://localhost:8080).
Verify connectivity:
- Check server logs for readiness
- From your external application, attempt to register the MCP server and send a basic command to manipulate a GIMP object

Prerequisites note: Ensure GIMP 3 is available in the bridge/plugin environment and that the GIMP MCP Bridge Server is running and connected to the GIMP instance before starting the MCP server.

Additional notes

Environment variables can customize how the MCP server talks to the GIMP bridge and the container environment. Common considerations include ensuring the GIMP bridge is reachable from the MCP server container, handling authentication if enabled, and exposing the MCP API on a known port. The GIMP MCP setup emphasizes serialization of GIMP objects to JSON for consumption by LLMs or agents, so verify the serialization schema matches what your clients expect. If you run into container networking issues, confirm that the GIMP bridge and MCP server share the same network or are reachable via the configured GIMP_HOST and GIMP_PORT settings. For development, you can enable DEBUG mode to get verbose logs helpful for troubleshooting.