gimp MCP (Maorcc)

GIMP MCP

演示

完整演示（带音频）：https://github.com/maorcc/gimp-mcp/raw/main/docs/demo.mp4

*AI代理使用GIMP MCP删除背景、编辑角色的表情并验证结果——所有这些都是通过Claude的自然语言完成的*

______________________________________________________________________

概述

GIMP MCP通过以下方式将GIMP的专业图像编辑功能与AI助手连接起来 模型上下文协议它允许你通过描述你想要的内容来编辑图像，并为人工智能提供了一个实时的视觉反馈渠道，以便在继续之前验证每一个变化。

它与其他GIMP集成有何不同：

• AI可以 *看见* 在工作流中的任何点保存图像，而不保存到磁盘(get_state_snapshot)
• 支持完全自主的多步管道：开放式→ edit → 验证→ 精炼→ 出口
• 56个专用工具命令，涵盖GIMP的每个主要操作
• 与GIMP 3.2.x完全兼容（解决了API的所有突破性更改）

主要特点

它能做什么？

迭代验证背景去除

AI移除背景，拍摄快照以检查结果，检测剩余像素，并循环直到图像干净：

"Remove the background from this image and keep looping until only the character remains"

表达式编辑

"Make the character smile — paint a smile arc with teeth over her mouth"

复杂的多级管道

"Open navi_portrait.png, remove the background, verify it's clean,
 then make her smile and export the final result as a PNG"

色彩和色调工作

"Boost the contrast, shift the hue 15 degrees warmer, then show me a before/after zoom of the face"

文本与合成

"Add a bold title at the top in white with a subtle drop shadow, then export for web"

______________________________________________________________________

先决条件

• 万向节3.2+ --在GIMP 3.2.2（Windows、macOS、Linux）上测试
• Python 3.8+ --对于MCP服务器
• 紫外线 --Python包管理器(pip install uv)
• MCP兼容AI客户端 --Claude Desktop、Claude Code、Gemini CLI、PydanticAI等。

______________________________________________________________________

快速开始

1.安装依赖项

git clone https://github.com/maorcc/gimp-mcp.git
cd gimp-mcp
uv sync

2.安装GIMP插件

复制 gimp-mcp-plugin.py 转到GIMP的插件目录并重新启动GIMP。

Linux（标准）：

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

Linux（Snap）：

mkdir -p ~/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

macOS：

mkdir -p ~/Library/Application\ Support/GIMP/3.0/plug-ins/gimp-mcp-plugin
cp gimp-mcp-plugin.py ~/Library/Application\ Support/GIMP/3.0/plug-ins/gimp-mcp-plugin/
chmod +x ~/Library/Application\ Support/GIMP/3.0/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py

窗户：

%APPDATA%\GIMP\3.2\plug-ins\gimp-mcp-plugin\gimp-mcp-plugin.py

Windows上不需要chmod。只需复制并重新启动GIMP。

对于所有平台： GIMP插件安装指南

3.在GIMP中启动MCP服务器

1. 在GIMP中打开任何图像
2. 首选 工具>启动MCP服务器
3. 服务器启动于 localhost:9877

4.配置您的MCP客户端

克劳德桌面版

~/.config/Claude/claude_desktop_config.json （Linux/macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

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

克劳德代码

cd /path/to/gimp-mcp
claude  # .mcp.json is auto-detected

或手动：

claude mcp add gimp-mcp -- uv run --directory /full/path/to/gimp-mcp gimp_mcp_server.py

Gemini CLI

~/.config/gemini/.gemini_config.json:

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

PydanticAI

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

server = MCPServerStdio('uv', args=['run', '--directory', '/path/to/gimp-mcp', 'gimp_mcp_server.py'])
agent = Agent('openai:gpt-4o', mcp_servers=[server])

______________________________________________________________________

可用的MCP工具

👁️ 视觉反馈

get_state_snapshot(image_index, max_size, region, label)

返回当前图像状态的实时PNG，这是AI的主要反馈机制。在任何编辑之间调用此命令，以验证结果而不保存到磁盘。

# Full image snapshot
snapshot = get_state_snapshot(max_size=512)

# Zoom into a face region for detail inspection
snapshot = get_state_snapshot(
    region={"x": 140, "y": 80, "width": 240, "height": 300},
    max_size=512,
    label="face-check"
)

这实现了迭代代理工作流： edit → 快照→ 评估→ 精炼→ 重复.

get_image_bitmap(image_index, max_width, max_height, region)

使用区域提取和缩放功能获取低级位图。返回base64编码的PNG。

🎨 调整

🔄 变换

✂️ 选集

🗂️ 图层

🖌️ 绘图和填充

🔤 文本

✨ 滤镜及特效

📁 文件操作

🔍 信息与背景

______________________________________________________________________

AI代理反馈循环

这 get_state_snapshot 该工具启用了一种模式，在这种模式下，AI会循环，直到目标被视觉确认：

┌─────────────┐
│  Apply edit │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│ get_state_      │  ← AI sees live PNG, no disk save needed
│ snapshot()      │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐     ┌──────────────────┐
│ Goal achieved?  │─ No─▶ Adjust & retry   │
└──────┬──────────┘     └──────────────────┘
       │ Yes
       ▼
┌─────────────┐
│   Export    │
└─────────────┘

示例：迭代背景去除

看 bg_remove_iterative.py 举一个完整的例子。AI：

1. 使用边缘种子连续选择删除背景
2. 拍摄快照以检查结果
3. 扫描剩余的背景彩色像素
4. 使用逐渐精细的网格（25px）运行有针对性的删除过程→ 1px)
5. 对孤立像素运行最后一次去斑过程
6. 循环直到没有背景像素

______________________________________________________________________

示例脚本

运行测试套件以验证您的设置：

python run_tests.py
# Expected: 56/56 PASSED

______________________________________________________________________

技术架构

插件↔ 服务器通信

AI Client (Claude, etc.)
      │  MCP (stdio)
      ▼
gimp_mcp_server.py          ← MCP tool definitions
      │  TCP JSON  :9877
      ▼
gimp-mcp-plugin.py          ← Runs inside GIMP process
      │  PyGObject
      ▼
GIMP 3.2 (gi.repository.Gimp)

• MCP服务器将工具调用转换为JSON命令，通过TCP发送到插件
• 插件通过PyGObject直接在GIMP进程中执行操作
• 两种消息格式： {"type": "...", "params": {...}} 对于命名工具， {"cmds": ["python..."]} 用于任意exec

GIMP 3.2兼容性说明

GIMP 3.x从GIMP 2.x引入了突破性的API更改。此版本中包含的关键修复程序：

______________________________________________________________________

故障排除

“无法连接到GIMP”

• GIMP必须在图像打开的情况下运行
• 启动MCP服务器： 工具>启动MCP服务器
• 检查端口9877是否未被防火墙阻止

插件在GIMP中不可见

• 确认插件文件在正确的目录中（请参阅上面的安装步骤）
• 在Linux/macOS上：确保文件具有执行权限(chmod +x)
• 安装后重新启动GIMP
• 检查 过滤器>脚本功能>控制台 用于错误消息

测试失败

运行测试套件并检查故障列表：

python run_tests.py

每个故障都包括工具名称和错误——GIMP 3.2上的大多数问题都包含在上述修复中。

调试模式

GIMP_MCP_DEBUG=1 uv run --directory /path/to/gimp-mcp gimp_mcp_server.py

______________________________________________________________________

输出示例

*“给我画一张脸和一只羊”——完全通过GIMP MCP的自然语言生成*

______________________________________________________________________

未来的增强功能

• 📚 食谱收集：可重复使用的工作流程模板（肖像清理、产品照片等）
• ↩️ 撤消系统：通过MCP进行历史管理和回滚
• 🚀 动态发现：从GIMP的完整PDB程序数据库自动生成MCP工具
• 🔒 安全：对不受信任的命令输入进行沙盒执行
• ⚡ 演出：针对大图像优化位图传输
• 🌐 远程访问：网络可访问的GIMP实例

______________________________________________________________________

贡献

欢迎贡献——bug修复、新工具、文档或示例脚本。在GitHub上打开PR或问题。

开发设置

安装开发依赖项并激活预提交挂钩，以便 ruff 在每次提交时运行：

uv sync
uv run pre-commit install

在此之后， ruff 检查每个上的暂存文件 git commit （与 --fix 自动应用）。同样的检查在CI中运行，因此钩子只是一个快速的本地安全网。

要稍后碰撞固定钩版本，请执行以下操作：

uv run pre-commit autoupdate