GIMP MCP

<!-- markdownlint-disable MD033 --> <div align="center"> <img src="resources/docs/logos/wilbericon.svg" alt="Wilber Icon" height="100" /> <img src="resources/docs/logos/mcp.svg" alt="MCP Logo" height="100" /> </div> <!-- markdownlint-enable MD033 -->

GIMP (GNU Image Manipulation Program) integration with MCP (Model Context Protocol). Allows external AI models and applications to control GIMP remotely.

Table of Contents

• GIMP MCP
  • Table of Contents
  • Introduction
    • Architecture
    • Features
  • Installation
    • Environment Variables
    • GIMP Containerization
  • Usage
    • Examples
  • Contributing
  • Related Projects

Introduction

Architecture

%%{init:{
  "iconSize": 24
}}%%
flowchart LR
    subgraph gimp["GIMP 3"]
        direction TB
        mcp-plugin["GIMP MCP Plugin"]
    end

    plugin-server["Bridge Server"]
    mcp-server["GIMP MCP Server"]

    subgraph apps["
        External Applications
        <br>
        <div style='display: flex; gap: 10px;'>
            <img src='resources/docs/logos/claude-color.svg' height='30' width='30'/>
            <img src='resources/docs/logos/gemini-color.svg' height='30' width='30'/>
            <img src='resources/docs/logos/openai.svg' height='30' width='30'/>
        </div>
        "]

    end

    apps <--> mcp-server
    mcp-plugin <--> plugin-server
    mcp-server <--> plugin-server

This project is comprised of two main components:

• GIMP MCP Plugin: Opens a server to act as a bridge between a running GIMP application and the GIMP MCP server. Executes commands received from the MCP server to control GIMP.
• GIMP MCP Server: Connects to the bridge server to send commands from external applications.

By splitting up the functionality between these two components, we isolate the GIMP-specific logic in the plugin, which allows for easier integration by end-users and facilitates MCP server development.

Features

• GIMP 3 Support: The plugin and server are designed to work with GIMP 3 via its Python SDK.
• Command Execution: The plugin executes commands received from the MCP server, allowing external applications to manipulate GIMP objects.
• Extensibility: The plugin can be extended to support additional GIMP features and commands, making it adaptable to various use cases.
• Object Serialization: The plugin serializes GIMP objects (e.g., images, layers, paths, selections) into JSON, which can be sent over the MCP protocol and provided to LLMs or agents as contextual input.
• Containerized Execution: The plugin and server can run in a containerized environment, allowing for easy setup and development.
• Containerized/Remote GIMP: The plugin supports running GIMP in a containerized environment with VNC-based browser access, making it easy to prototype and develop without needing a local GIMP installation.

Installation

The MCP server and plugin are designed to work with GIMP 3 only. To install the GIMP MCP Plugin and Server, follow these steps:

• GIMP MCP Plugin Installation Instructions.
• GIMP MCP Server Installation Instructions.

Environment Variables

Both the GIMP MCP Plugin and the GIMP MCP Server can be configured using environment variables. Please check the environments/example.env file in this repository for a list of available environment variables and their descriptions.

GIMP Containerization

For quick prototyping and development purposes, we support running GIMP 3 in a containerized environment with VNC-based browser access. To know more, check out the docker-compose.yaml file in this repository.

To run GIMP 3 versions, we use a custom Docker image based on linuxserver/gimp, which builds upon kasmweb/gimp. Since those images don't officially support GIMP 3 yet, we download a GIMP 3 AppImage and replace the GIMP binary in the container. This is a workaround that won't be necessary once GIMP 3 is officially supported in the linuxserver/gimp image.

Usage

To start using the GIMP MCP Plugin and Server, follow these steps:

• Open GIMP 3
• Start the GIMP MCP Bridge Server by executing the start server action in the plugin
• Start the GIMP MCP Server
• Register the MCP server with your external application

After these steps, you can start asking questions about GIMP objects, executing commands, and manipulating images, layers, paths, and selections using models connected via the MCP protocol.

Examples

We provide examples of how to use the GIMP MCP Plugin and Server:

• OpenAI Agents SDK Example

Contributing

We welcome contributions to the GIMP MCP Plugin and Server! If you have ideas for new features, improvements, or bug fixes, please open an issue or submit a pull request. You can also check the TODOs for ideas on what to work on next.

Adding functionality to the GIMP MCP Plugin and Server is straightforward. For instance, to add a new GIMP operation, follow these steps:

1. Implement the desired functionality in the GIMP MCP Plugin operations module, which will handle the GIMP-specific logic.
2. Add the corresponding commands to the GIMP MCP Server in the tools module to expose that functionality over the MCP protocol.

We provide a VS Code workspace with recommended settings and extensions to help you get started quickly. You can also check out the stubs generator to generate type stubs for GIMP's Python API, which can be useful for developing plugins and scripts.

Related Projects

• libreearth/gimp-mcp
• mikechambers/adb-mcp
• loonghao/photoshop-python-api-mcp-server
• SureScaleAI/openai-gpt-image-mcp