gimp-mcp

让大模型通过自然语言驱动 GIMP 3 完成图像处理的 MCP 服务。

MCP 客户端（大模型）
    │ stdio（MCP 协议）
    ▼
本服务（Python，FastMCP）
    │ 工具调用 → 生成 Script-Fu → 发送执行 → 解析返回
    ▼ TCP（GIMP Script-Fu Server，127.0.0.1:10008）
GIMP 3（桌面实例，实时可见操作过程）

设计原则：确定性操作走封装工具，长尾操作走万能出口（默认关闭），全程支持视觉/数值反馈闭环。

环境要求

• Windows 11（其他平台未实测）

• GIMP 3.x（本仓库在 GIMP 3.2.6 上实测；Script-Fu 过程名以 3.x 为准，2.x 不可用）

• Python 3.12+（本仓库在 3.13 上实测）

Related MCP server: GimpMCP

安装

cd gimp-mcp
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

启动步骤

1. 启动 GIMP 并开启 Script-Fu Server（三选一）

方式 A（推荐，双击即用）：双击项目根目录的 start-gimp-mcp.bat——它会打开 GIMP 界面并自动开启 Script-Fu Server，AI 的每一步操作你都能实时看到；脚本会先检测端口，已启动则不会重复拉起。无头模式：start-gimp-mcp.bat -Headless。

方式 B（GUI 手动）：启动 GIMP → 滤镜（Filters）→ Development → Script-Fu → Start Server，端口保持 10008。

方式 C（命令行，无头）：

gimp-console-3.2.exe --batch-interpreter=plug-in-script-fu-eval --batch "(plug-in-script-fu-server 1 \"127.0.0.1\" 10008 \"\")"

首次启动约需 10–15 秒。服务不代管 GIMP 进程，需保证 Script-Fu Server 先于本服务就绪。

注意：务必让 MCP 服务连接你正在看的那个 GIMP 实例。方式 A 启动的 GUI 实例自带 Server；若用方式 C 起了无头实例又另开 GUI，AI 操作的是看不见的无头实例。

2. 在 MCP 客户端注册本服务

以 Claude Desktop / Kimi Code 的 MCP 配置为例：

{
  "mcpServers": {
    "gimp": {
      "command": "C:\\path\\to\\gimp-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\gimp-mcp\\server.py"],
      "cwd": "C:\\path\\to\\gimp-mcp"
    }
  }
}

将示例中的 C:\path\to\gimp-mcp 替换为你的实际克隆路径。

用 MCP Inspector 调试：

.venv\Scripts\mcp dev server.py

3. 验证

在 MCP 客户端调用 ping，返回 GIMP 版本号即链路打通。

配置（config.json）

工具一览（33 个）

• 连接：ping、get_image_info、list_fonts（查询已安装字体名，供 add_text 使用）

• 文件：open_image、new_image、export_image、save_xcf

• 几何：crop_to_rect、crop_to_aspect、scale_image、resize_canvas、rotate_image、flip_image

• 选区：select_all、select_none、select_invert、select_rect、select_ellipse、fill_selection

• 图层：add_layer、remove_layer、set_active_layer、duplicate_layer

• 调色/滤镜：adjust_brightness_contrast、adjust_levels、adjust_hue_saturation、desaturate、gaussian_blur、unsharp_mask（以上 6 个支持 selection_only）、add_text（文字图层，不支持 selection_only）

• 反馈回路：export_preview（降采样预览图供多模态模型看图验收）、get_histogram_stats（均值/中位数/标准差/黑白场占比的数值反馈）

• 万能出口：run_scriptfu（默认关闭）

所有工具返回统一结构 {ok, result?, error?}；GIMP 端失败时 error 原样带回 Script-Fu 错误文本，便于大模型自我纠正重试。

⚠️ 安全警告

1. 本服务只对本地负责：socket 目标硬编码 127.0.0.1，无法也不应改为远程地址。

2. 文件操作被限制在白名单目录（默认仅项目内 workspace/）。open_image / export_image / save_xcf 越界即拒绝。

3. run_scriptfu 默认关闭。把 config.json 的 enable_scriptfu_escape_hatch 改为 true 后，等价于允许 AI 执行任意 Scheme 代码——可读写当前用户有权限的任何文件、可调用任意 GIMP 插件。只在你信任所连接的 MCP 客户端与模型时开启。

4. 所有 Scheme 代码拼接处均做参数转义；如发现可注入路径请提 issue。

测试

# 无头单测（不需要 GIMP）
.venv\Scripts\pytest

# 无头 Scheme 合法性验证（需要 gimp-console，较慢）
.venv\Scripts\pytest -m headless

# live 集成测试（自动启动独立 GIMP，使用临时配置、端口和输出目录）
.venv\Scripts\pytest -m live

# 全套测试（unit + headless + live）
.venv\Scripts\pytest -m ""

# 端到端验收（仅对专用测试后端运行；会写 workspace/photo.jpg 等固定文件）
.venv\Scripts\python scripts\e2e_acceptance.py

已知事项

• 「当前图像」的口径：一律指 gimp-get-images 首元素，即最近创建/加载的图像，不是 GIMP 界面焦点所在的那张。目前不支持在多张已打开图像之间切换，也没有关闭图像的工具——长时间会话里图像只增不减，建议处理完一张再开下一张。

• get_histogram_stats 在 200 万像素图像上约需 18 秒（GIMP 端 histogram 计算较慢）；3000 万像素级操作建议把 timeout_seconds 调大。直方图受当前选区限制，要看全图统计请先 select_none。

• 自动重试仅限于尚未发送脚本时的连接建立失败（默认重试 3 次、间隔 2 秒）。一旦开始发送，发送异常、响应断线、超时及协议错误均关闭连接且不重放；操作可能已经执行，请检查 GIMP 状态后再决定是否重试。

• export_preview 默认生成 JPEG，若扩展名白名单未允许 jpg，请显式传入已获允许的 .png 路径。默认路径同样检查目录联接/符号链接和扩展名白名单。

• duplicate_layer 将副本放在源层同一父级、紧邻源层上方并选中；不会把底层副本直接置于整个图像最前面。半透明或特殊混合模式图层被复制后仍可能改变合成效果。

• 日志初始化失败时不执行图像操作；操作完成后的日志记录异常不会将成功改报失败，返回值会附带 warning，不要因此重试图像操作。

• GIMP 本地化会影响自动生成的图层名（如副本后缀、导入图层名），按名称操作图层时以 get_image_info 返回为准。

• 协议与 PDB 兼容性说明见 docs/protocol.md。

目录结构

gimp-mcp/
├── server.py            # MCP 服务入口（FastMCP）
├── gimp_client.py       # Script-Fu TCP 客户端（协议封装）
├── scheme.py            # Scheme 生成/转义/结果解析
├── config.py / config.json
├── tools/               # 按域分组的工具实现
├── tests/               # pytest（unit / headless / live）
├── scripts/             # 冒烟、端到端验收与 PDB 辅助脚本
├── workspace/           # 默认白名单目录
├── logs/                # 调用日志
└── docs/                # 协议与兼容性说明