gimp-mcp

一个驱动 GIMP 3 进行脚本化图像编辑的 MCP 服务器：裁剪、调整大小、 宽高比适配、轻度颜色修饰、尺寸规格验证，以及跨文件夹的批量处理。

在 Windows 上的 GIMP 3.2.4 中构建并验证，使用 GIMP 3 的 GObject Introspection Python API（gi.repository.Gimp），而不是旧的 2.x Script-Fu 接口。

它的用途

任何需要反复对图像应用相同确定性处理的工作流，而你更愿意描述它而不是点击它：

• 将照片裁剪到目标宽高比，或裁剪到最大的居中正方形

• 调整一个文件夹中的图像大小，使最长边最多为 2000px

• 在发布前检查图像是否满足尺寸/方向要求

• 在一次操作中对整个拍摄应用一个裁剪和调整大小流水线

Related MCP server: gimp-mcp

最可能坑你的一点：EXIF 方向

来自手机和许多相机的照片通常以横向存储，并带有 EXIF 方向标签，告诉查看者旋转它们。每个人看到的 3000x4000 纵向照片可能存储为 4000x3000。

GIMP 的非交互式加载器不会应用该标签。 因此，一个简单的“居中裁剪为正方形”会裁剪错误的轴并产生侧向图像——同时仍然报告看似合理的尺寸，所以在你打开输出之前，一切看起来都没有明显问题。

本项目中的每次加载都通过 load_image()，它首先调用 Gimp.Image.policy_rotate()，因此所有几何——以及此服务器报告的每个尺寸——都是显示方向，即查看者实际看到的内容。这由一个测试覆盖。

架构

两个执行后端，一个共享的操作运行时：

                    ┌───────────────────────────────┐
  MCP client ──────►│  gimp_mcp/server.py (stdio)   │
                    └───────────┬───────────────────┘
                                │
              ┌─────────────────┴──────────────────┐
              ▼                                    ▼
   HeadlessBackend                        BridgeBackend
   spawns gimp-console-3.exe              TCP 127.0.0.1:50472
   (no running GIMP needed)               (into a running GIMP)
              │                                    │
              ▼                                    ▼
      bootstrap.py                    plug-ins/gimp-mcp-bridge/
              │                                    │
              └──────────────┬─────────────────────┘
                             ▼
              gimp_mcp/gimp_runtime.py
              THE single source of truth for every
              image operation. Both paths share it,
              so batch and live cannot drift apart.

install_plugin.py 在安装的插件旁边写入一个 runtime_path.txt 指针，而不是复制 gimp_runtime.py，因此磁盘上只存在一份操作代码。

后端选择。 headless 是默认值，也是所有批量和确定性工作使用的——它不需要打开 GIMP，是可靠的路径。 bridge 用于对已打开的文档进行实时工作。两者都经过验证，可产生像素级相同的输出。

为什么用 TCP 而不是 D-Bus

现有的实时 GIMP 控制项目使用 D-Bus，而 D-Bus 在 Windows 上不存在。回环 TCP 套接字实现了同样的功能，并且是跨平台的。它仅绑定 127.0.0.1，绝不暴露到网络。

安装

需要 GIMP 3.x（针对 3.2.4 开发）和 mcp Python 包。

关于 mcp 依赖的说明。 这针对 mcp 1.x SDK，并固定为 mcp>=1.0,<2。2.0 版本移除了 mcp.server.fastmcp，并将 FastMCP 重命名为 MCPServer；移植到它尚未完成，未固定的安装会获取 2.x 并在导入时失败。

pip install -r requirements.txt
python install_plugin.py          # install the bridge plug-in (optional)
python install_plugin.py --list   # show detected GIMP config dirs

桥接插件仅用于实时控制工具。批量和单图像工具无需在 GIMP 中安装任何东西即可工作。

插件位置

install_plugin.py 发现实际存在的任何 GIMP 3.x 配置目录，而不是硬编码版本。在 Windows 上，那是：

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

注意它是带版本的目录（GIMP 3.2 为 3.2，而不是 3.0），并且 GIMP 3 要求每个插件位于一个与 .py 文件同名的文件夹中。在 Linux 和 macOS 上，安装程序分别查看 ~/.config/GIMP/3.x/ 和 ~/Library/Application Support/GIMP/3.x/。

注册 MCP 服务器

安装该包会提供一个 gimp-mcp 控制台脚本，这是最简洁的注册方式，因为它不依赖于工作目录：

python -m venv .venv
.venv/Scripts/python -m pip install -e .     # .venv/bin/python on Unix

{
  "mcpServers": {
    "gimp": {
      "type": "stdio",
      "command": "/path/to/gimp-mcp/.venv/Scripts/gimp-mcp.exe",
      "args": []
    }
  }
}

使用 Claude Code，等效的一行命令是：

claude mcp add gimp --scope user -- /path/to/gimp-mcp/.venv/Scripts/gimp-mcp.exe

直接运行模块也可以，如果 mcp 在该解释器中可导入：

{
  "mcpServers": {
    "gimp": {
      "command": "python",
      "args": ["-m", "gimp_mcp"],
      "cwd": "/path/to/gimp-mcp"
    }
  }
}

可选的环境变量：

工具

检查

单图像

批量

整个批次在一次 GIMP 调用中运行。GIMP 的控制台需要几秒钟才能启动，因此逐文件生成会慢——对于小文件夹，测量约为每文件便宜 ~2.4 倍，并且节省随文件夹大小增长。失败的文件不会中止运行；它会进入 errors，其余继续。

实时控制（需要桥接插件）

在 GIMP 中启动桥接：滤镜 > 开发 > 启动 MCP 桥接。

图像规格

check_image_spec、fit_to_spec 及其批量等效项共享一个规格模型。每个约束都是可选的——0 表示无限制，方向 any 表示无方向要求。

fit_to_spec 按三个有序步骤满足规格：裁剪以修正方向，放大以达到最小值，缩小以尊重最大值。已满足的约束保持取景不变。

// A square image at least 1000x1000, capped at 2000x2000
{ "orientation": "square", "min_width": 1000, "min_height": 1000,
  "max_width": 2000, "max_height": 2000 }

颜色调整是刻意受限的

adjust_image 将亮度/对比度限制在 -0.5..0.5，并拒绝超出该范围的任何值，而不是裁剪。超过大约 ±0.15 的值会明显改变照片的特性，这在图像需要忠实表现真实主体时很重要。故意没有饱和度提升或“自动增强”。

验证

运行测试套件：

python -m pytest tests/ -v

需要真实图像的测试会被跳过，除非你指向一些：

export GIMP_MCP_TEST_IMAGE=/path/to/photo.jpg          # ideally EXIF-rotated
export GIMP_MCP_TEST_REFERENCE=/path/to/photo-square.jpg

GIMP_MCP_TEST_REFERENCE 应该是 GIMP_MCP_TEST_IMAGE 的独立制作的中心正方形裁剪——例如，在 GIMP 中手工裁剪。头条测试断言 crop_square 重现该参考，而不仅仅是运行无错误。

在开发期间使用的参考照片上（一个 4000x3000 JPEG，EXIF 方向 6，显示为 3000x4000）：

crop_square vs hand-made reference : mean abs diff 0.236, max 18, outliers 0.0014%
same crop via the bridge backend   : mean abs diff 0.236, max 18, outliers 0.0014%

该残差是 JPEG 重新编码噪声——仅重新编码就给出 ~0.5 均值——不是几何差异，并且两个后端完全一致。

该套件还涵盖显示方向报告、方向和最小尺寸规格、越界裁剪被拒绝、超出范围的调整被拒绝、亮度按正确方向移动像素、链式流水线、宽高比裁剪、跨文件夹批量、只读审计、缺失文件的清晰错误，以及真实 MCP stdio 协议的完整通过。

故障排除

gimp-console not found — 将 GIMP_CONSOLE 设置为 gimp-console-3.exe 的完整路径。

桥接工具失败并显示“Could not reach the GIMP bridge” — GIMP 未打开，或桥接未启动。运行 滤镜 > 开发 > 启动 MCP 桥接。gimp_status 同时显示两个后端。

安装后菜单项缺失 — 重启 GIMP；它只在启动时扫描插件。确认布局是 plug-ins/gimp-mcp-bridge/gimp-mcp-bridge.py（文件夹名称必须与文件名匹配）。

诊断插件 — GIMP 插件是一个单独的进程，其 stderr 在 Windows 上以 GUI 应用运行时不可见。桥接写入 bridge.log，位于安装的插件旁边。

颜色配置文件对话框在启动时阻止 GIMP，当在 GUI 模式下打开带有嵌入配置文件的图像时。它在无头模式下不会出现，这是批量工作使用无头后端的另一个原因。

批量超时 — 默认整个运行 600 秒；非常大的文件夹可能需要更多。

已知限制

• 实时控制仅得到轻度使用。 已验证其可用（通过桥接打开图像、列出、截图、实时编辑和裁剪，输出与无头模式相同），但使用量远少于无头路径。请将无头模式视为可信赖的路径。

• 桥接按设计执行任意 Python 代码。 它仅限回环，且为手动启动而非自动启动，但任何能访问机器上 localhost 的内容都可以在 GIMP 运行时驱动它。不使用时请停止它。

• 桥接启动会阻塞其自身的插件进程 —— 这正是使其保持存活的原因。它不会冻结 GIMP 的 UI，但 GIMP 会显示该插件正在运行。

• GUI 菜单项本身未覆盖自动化测试。 其调用的过程已验证；点击路径未验证。

• 仅验证了 Windows。 代码路径是跨平台的，安装程序也处理 Linux/macOS 配置目录，但两者均未经过测试。

• 尚不支持 mcp 2.x SDK —— 请参阅 Install 下的说明。

• 无 AI 背景移除或风格迁移。 一些类似项目宣称具备这些功能，但背后没有可用的实现；此处有意不做此类宣称。

关于先前作品的说明

GIMP 端插件暴露桥接与独立 MCP 服务器进程作为客户端连接之间的拆分，是解决此问题的自然形态，其他 GIMP MCP 项目也采用此方式。批处理和预设式流水线在多个项目中很常见。实时画布控制在其他地方通过 D-Bus 实现，此处以回环 TCP 替代以支持 Windows。未从其中任何项目复制代码；Windows 特有的细节 —— 真实插件路径、插件进程生命周期、运行回调签名以及 EXIF 行为 —— 均直接针对 GIMP 3.2.4 确定。

许可证

MIT —— 参见 LICENSE。