Gimp MCP

🚀 GIMP MCP

This project empowers non-technical users to edit images with GIMP via simple conversational commands, bridging the gap between GIMP's powerful capabilities and natural language interaction. It also enables professionals to execute complex multi-step workflows more rapidly than traditional point-and-click methods.

🚀 Quick Start

This project allows users to edit images in GIMP using simple conversational commands. Non-technical users can easily achieve various image editing effects, and professionals can also execute complex workflows more efficiently.

✨ Features

• Natural Language Interaction: Users can describe image editing requirements in natural language, and the system will translate them into precise GIMP operations.
• Suitability for Different Users: It meets the needs of both non-technical users and professionals, improving work efficiency.
• Full Functionality Exposure: All GIMP features are exposed via MCP.

📦 Installation

Prerequisites

• GIMP 3.0 and above: This project is developed and tested with GIMP 3.0.
• MCP-compatible AI client: Claude Desktop, Gemini CLI, PydanticAI, or other MCP clients.
• uv: A modern Python package installer and resolver.

Steps

1. Install the GIMP plugin for mcp server

To install the plugin, copy the gimp-mcp-plugin.py to your GIMP plug-ins directory.

For detailed instructions on locating your GIMP plugins folder across different operating systems, please refer to this guide:

GIMP Plugin Installation Guide (Wikibooks)

Make sure the plugin file has "execute" permission.

For example, if your GIMP is installed with snap, you can use the following commands to copy the plugin to the correct directory:

mkdir ~/snap/gimp/current/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin
cp gimp-mcp-plugin.py ~/snap/gimp/current/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin
chmod +x ~/snap/gimp/current/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py

Restart GIMP.

Open any image in GIMP, and then you should see a new menu item under Tools > Start MCP Server. Click it to start the MCP server.

2. Configure MCP Client

Claude Desktop

Add these lines to your Claude Desktop configuration file. (On Linux/macOS: ~/.config/Claude/claude_desktop_config.json )

{
  "mcpServers": {
    "gimp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "your/path/to/gimp-mcp-server",
        "server.py"
      ]
    }
  }
}

Gemini CLI

Configure your Gemini CLI MCP server in ~/.config/gemini/.gemini_config.json:

{
  "mcpServers": {
    "gimp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "your/path/to/gimp-mcp-server",
        "server.py"
      ]
    }
  }
}

PydanticAI

For PydanticAI agents, use the MCPServerStdio class:

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

server = MCPServerStdio(
    'uv',
    args=[
        'run',
        '--directory',
        'your/path/to/gimp-mcp-server',
        'server.py'
    ]
)

agent = Agent('openai:gpt-4o', mcp_servers=[server])

Other MCP Clients

For other MCP clients that support stdio transport, use the command:

uv run --directory your/path/to/gimp-mcp-server server.py

💻 Usage Examples

Basic Usage

Note: Ensure your MCP client is configured with the GIMP MCP server before starting.

1. Open any image in GIMP, Under Tools menu click Start MCP Server.
2. Start your MCP client (Claude Desktop, Gemini CLI, etc.)
3. Tell the AI to interact with GIMP, like "Draw a face and a sheep with Gimp".

Example output from the prompt "draw me a face and a sheep" using GIMP MCP

📚 Documentation

Suggestions for Improvement

• Add Recipes: Create a collection of common GIMP tasks and workflows as MCP recipes.
• Undo capabilities: Implement a way to undo actions in GIMP through the MCP interface.
• Visual feedback: Provide visual feedback to the MCP client for actions performed in GIMP, such as showing the modified image or layer.
• API discovery: Create dynamic tool discovery that exposes available GIMP functions as separate MCP tools instead of requiring manual PyGObject code
• Error context: Enhance error messages with specific GIMP API context, line numbers, and suggested fixes for common issues
• GIMP plugin robustness: Make sure resources are released appropriately, and prevent misconduct from mcp client on the PyGObject API.

🤝 Contributing

Contributions are welcome! Whether it's bug fixes, new features, or documentation improvements, feel free to submit a Pull Request or open an issue.

📄 License

This project is licensed under the GPL v3 License. View License