GIMP Agent MCP

GIMP Agent MCP

让 AI Agent 在 GIMP 中编辑。保留图层。查看更改。

将 Claude、Codex、Cursor 或其他 MCP 客户端连接到 GIMP 3。Agent 可以在已打开的窗口中工作、检查结果、优化编辑，并保存可继续编辑的 XCF。无头模式可对图像文件夹运行相同的工作流。

查看实际效果

观看 20 秒 MP4 · 打开可编辑的 XCF · 重现 MCP 会话

这段演示逐步录制了实际的 GIMP 窗口，并缩短了停顿时间。通过 MCP 批量更改了三个文本图层。一次 Ctrl+Z 即可还原全部三项更改；Ctrl+Y 可恢复更改。文本、插图和背景分别保留在独立的命名图层中。这展示的是真实工具执行过程，并不意味着每个模型都会根据提示词采取相同的操作方案。

试着这样提问

“更改这张卡片的标题和辅助文本。将它们保留为文本图层，把这些编辑合并为一个撤销步骤，并在导出前向我展示结果。”

“把这幅透明背景的插图制作成带白色描边和阴影的 Telegram 贴纸。保存为 512 × 512 PNG。”

“将这些尺寸相同的 PNG 帧打包成精灵图。保留一份 XCF 母版，写入图集 JSON，并验证导出像素与原图一致。”

随附的技能指南涵盖分层插图、精灵图和批处理任务。它们会指导 Agent 在宣布任务完成前检查并测量实际输出。

安装

你需要 GIMP 3.2.x、Python 3.11+、uv 和一个 MCP 客户端。GIMP 必须与服务安装在同一台机器上。先启动一次 GIMP，以创建用户配置文件。

uvx gimp-agent-mcp install-plugin
uvx gimp-agent-mcp install-skills
uvx gimp-agent-mcp doctor

安装或升级桥接程序后，请重启 GIMP。在已打开的 GIMP 窗口中，选择 Filters → Development → Start Agent Bridge。

将以下配置添加到客户端的 MCP 设置中：

{
  "mcpServers": {
    "gimp": {
      "command": "uvx",
      "args": ["gimp-agent-mcp", "serve"]
    }
  }
}

对于 Claude Code：

claude mcp add gimp -- uvx gimp-agent-mcp serve

Claude Code 也可以将服务和技能作为插件安装；请参阅技能安装。如需 AI 背景移除，请使用 uvx --from "gimp-agent-mcp[segmentation]" gimp-agent-mcp serve 安装可选模型运行时（在 MCP 配置中使用相同参数）。首次使用时会下载模型；图像处理全程在本地完成。

**从源代码开始使用？**运行 uv sync --extra dev，然后运行 uv run gimp-agent-mcp install-plugin。将服务配置为 uv run --no-sync --directory /absolute/path/to/repo gimp-agent-mcp serve。当另一个服务正在运行时，--no-sync 可避免 Windows 可执行文件锁定错误。

在当前窗口中操作，或运行批处理

• **当前窗口：**从菜单启动桥接。继续手动编辑同一文档。
• 快捷方式：uvx gimp-agent-mcp shortcut 会创建一个启动器，用于在启动 GIMP 时启用桥接。
• 由 Agent 启动：gimp_launch(mode="gui") 会打开 GIMP；mode="headless" 则在无窗口模式下运行。

gimp_status 和 gimp_list_images 会报告与 GIMP 当前活动用户显示器关联的图像、选中的图层 ID、选区边界和脏状态。当用户说“这个图层”或“选区”时，编辑前先读取此上下文。对于特定文档，请使用 gimp_context(image_id)；也可以通过 present=true 将其置于前台。如果运行了多个桥接，gimp_status 会跟随最新的桥接文件；用户会话处于活动状态时，请隔离测试配置文件。

实用之处

能力	可获得的功能
视觉反馈	整幅图像、图层和区域预览；保存的快照；前后对比和差异对比。诊断叠加层可添加坐标网格、图层框、选区边界和带标签的点，且不会更改源文件。
可测量的输出	像素颜色、Alpha 边界、直方图和主色。精灵图打包会重新打开导出的 PNG，并将每个单元格解码后的 RGBA 像素与其源图像进行比较。
可编辑的作品	命名图层、文本、路径、蒙版和非破坏性图层效果。分别导出 XCF 主文件和交付文件。
日常编辑	三种精简工具涵盖常见调整、画布变换、填充和简单绘图。每项操作都会报告所使用的已安装 GEGL 或 PDB 操作。
一步撤销	gimp_edit_batch 可通过一次调用将受支持的编辑操作分组。gimp_undo_group 可跨多次调用保留对单张图像的编辑，直到结束，因此按一次 Ctrl+Z 即可撤销本轮操作。桥接连接断开时，其分组会关闭。
运行时发现	搜索并描述已安装的 PDB 过程和 GEGL 操作，包括参数名称、类型和枚举值。数值数组参数支持曲线和笔刷笔画。
可重复的任务	11 种配方和文件夹批处理，外加 3 个内置工作流技能。
如实处理失败	连接断开时，绝不会悄悄重放结果未知的编辑操作。重新连接并检查后，再决定是否重试。

其他 GIMP MCP 项目也提供 TCP 桥接和视觉反馈。本项目侧重于可编辑的输出、测量、分组编辑和可复现的验证。通用 API 访问范围很广，但不保证每个 GIMP 过程或 GEGL 操作都能与所有参数组合搭配使用。

工具（40）

类别	工具
学习和连接	gimp_help、gimp_status、gimp_launch、gimp_shutdown、gimp_context
图像	gimp_list_images、gimp_image_info、gimp_new_image、gimp_open、gimp_export、gimp_close_image
查看和测量	gimp_render、gimp_snapshot、gimp_drop_snapshot、gimp_render_compare、gimp_measure
PDB	gimp_pdb_search、gimp_pdb_describe、gimp_pdb_call
滤镜	gimp_filter_search、gimp_filter_describe、gimp_apply_filter、gimp_layer_effects、gimp_layer_effect
日常编辑	gimp_adjust、gimp_canvas、gimp_draw
结构化编辑	gimp_edit_batch、gimp_undo_group、gimp_select、gimp_layer_mask、gimp_layer、gimp_text、gimp_list_fonts、gimp_path
抠图	gimp_remove_background（可选的 rembg 模型运行时）
自动化	gimp_run_python、gimp_list_recipes、gimp_run_recipe、gimp_batch_recipe、gimp_brand、gimp_cancel

图像和项目使用整数 ID。颜色支持十六进制值、常见名称、CSS RGB 字符串或分量数组；枚举值使用 describe 工具返回的 nick。调用 gimp_help("batch") 查看分组编辑示例。gimp_run_python 可能被禁用，此时工具数量会减少一个。

常见操作不再需要发现过程。例如，使用 gimp_adjust(layer_id, "brightness_contrast", {"brightness": 0.15})、gimp_canvas(image_id, "crop", width=1200, height=630, x=40, y=20) 或 gimp_draw(image_id, layer_id, "line", color="#ffffff", x=20, y=40, x2=300, y2=40, line_width=6)。GIMP 支持时，调整默认使用可编辑的图层效果；画布和绘图操作则会将像素或结构直接写入图像。每项结果都会标明执行前选定的运行时操作。

若要进行视觉定位，可请求诊断预览，而不在工作图像上做标记：

gimp_render(image_id=3, overlay=["grid", "layers", "selection"], grid_size=100,
            points=[{"x": 600, "y": 340, "label": "headline centre"}])

配方

配方	用途
telegram_sticker	在透明的 512 × 512 画布上适配图像、添加描边和阴影。
compose	根据包含图像、文本、形状和效果的清单制作卡片和横幅。
sprite_sheet_pack	将有序且尺寸相同的 PNG 转换为经过验证的网格 PNG、分层 XCF 和图集 JSON，并可选择添加边距和间距。
sprite_atlas_pack	将尺寸各异的 PNG 转换为带留白、可选裁剪的图集 PNG、分层 XCF 和图集 JSON，并逐像素验证。
social_crop	围绕焦点位置，为指定社交媒体平台（Open Graph、X、Instagram、story、YouTube 或自定义平台）生成经测量和像素检查的输出。
sprite_sheet_slice	从精灵图中切出固定尺寸的图块，并可选择跳过空白单元格。
web_optimise	调整尺寸和导出质量，以满足文件大小预算。
icon_set	将正方形源图导出为多个尺寸。
watermark	定位文本或图像水印。
contact_sheet	生成带标签的文件夹缩略图。
fit_and_export	将图像适配到最大边长，并按扩展名导出。

用于 compose 的品牌套件

将品牌的颜色、字体、素材和画布尺寸保存一次，然后通过令牌引用。配置文件为 JSON 文件，存放在每位用户的配置目录中（Windows 上为 %APPDATA%\gimp-agent-mcp\brands，macOS 上为 ~/Library/Application Support/gimp-agent-mcp/brands，其他系统上为 $XDG_CONFIG_HOME/gimp-agent-mcp/brands；GIMP_AGENT_BRANDS_DIR 可覆盖此路径）。保存配置文件时，系统会根据正在运行的 GIMP 检查字体名称。

gimp_brand(action="set", profile={"name": "example",
  "colors": {"bg": "#0f1117", "accent": "#1f3a8a", "text": "#ffffff"},
  "fonts": {"headline": "Bahnschrift Bold"}, "assets": {"logo": "/brand/logo.png"},
  "canvases": {"x-card": [1200, 675], "og": [1200, 630]}})

gimp_run_recipe("compose", {"output_path": "out/card.png", "manifest": {
  "brand": "example", "canvas": "x-card", "background": "@bg",
  "items": [{"type": "image", "path": "@logo", "x": 40, "y": 40, "width": 160},
            {"type": "text", "text": "Launch day", "font": "@headline", "size": 72, "color": "@text", "x": 40, "y": 240}]}})

在任何内容传入 GIMP 之前，服务端会解析令牌，因此令牌清单最终会与手动编写的清单完全一致。仍可使用字面值，且字面值优先于配置文件；如果令牌未知，则会报错并列出配置文件名称及其可用键。完整规则请参阅 gimp_help("compose")。

配方参数和示例 · 素材工作流 · 技能

测试范围与限制

版本 0.5.0，测试版。已在 Windows GIMP 3.2.4、Linux GIMP 3.2.2（Ubuntu 26.04）以及 Apple Silicon 和 Intel 上的 macOS 15 GIMP 3.2.4 中进行测试。每个平台都会针对真实的 GIMP 运行完整的冒烟测试套件、定向能力验证，以及全部 23 项日常编辑操作。不支持 GIMP 2.10；当前测试矩阵不包含更早的 3.x 版本。

• gimp_edit_batch 支持范围受限的图层、文本、选区、路径、蒙版和滤镜编辑。gimp_undo_group(image_id, action="start", name="agent: sticker pass") 可跨调用保持一个分组；使用 action="end" 结束分组。gimp_status 会列出已打开的分组。客户端断开连接时会关闭其分组。桥接程序会跟踪提供的名称，但 GIMP 3 的公开撤销分组 API 无法设置撤销历史标签。用户可使用 GIMP 的撤销/重做功能；没有可通过程序调用的撤销端点。
• 在 GUI GIMP 会话中按一次 Ctrl+Z 后，uv run python scripts/undo_group_smoke.py 会针对操作前的快照检查三项编辑。无头模式下的 gimp-agent-mcp smoke 检查涵盖分组生命周期和断开连接后的清理。
• 某些 GEGL 源操作（包括线性渐变）不是可绘制滤镜。请改用 PDB 渐变填充过程。不保证与矢量扭曲/液化功能一致；请参阅扭曲调查说明。
• 精灵图打包支持相同尺寸的帧（sprite_sheet_pack，带边距和间距），或混合尺寸的 PNG 和已打开的图层（sprite_atlas_pack，带内边距和裁剪）。两者都不会对齐动画或旋转精灵图。
• 长时间运行的工作会报告进度，并可在检查点处使用 gimp_cancel 取消：在配方条目、批处理文件和编辑批处理步骤之间；在调用 checkpoint() 的 gimp_run_python 代码的各轮运行之间；以及滤镜启动前。已经开始运行的单次 GEGL 合并操作无法中断，GIMP 自身的逐过程进度目前也不会转发。

验证你的设置

uvx gimp-agent-mcp smoke
# From the source checkout:
uv run pytest
uv run python scripts/capability_proof.py /path/to/proof-output
uv run python scripts/everyday_proof.py /path/to/proof-output

CI 会检查受支持的 Python 版本，并通过独立任务在 Windows、Linux 和两种 macOS 架构上运行真实的 GIMP。发布依赖于全部三个真实 GIMP 工作流通过。通用能力验证会测量曲线、渐变和画笔输出，并检查批处理恢复、文档边界、诊断叠加层、嵌套预览和快照清理。第二项验证会解析并运行 gimp_adjust、gimp_canvas 和 gimp_draw 中的每项操作，并记录尺寸、图层数量和测量到的像素。请参阅验证详情。

每个冒烟测试和验证脚本都会在自行启动的 GIMP 上运行；关闭该 GIMP 时，会等待桥接程序确实退出（端口已关闭、桥接文件已移除、插件进程已退出）后才返回。收到关闭请求的桥接程序会立即拒绝新连接和新请求。冒烟测试会在 shutdown (bridge gone before return) 检查中断言这一点；CI 会设置 GIMP_AGENT_REQUIRE_OWN_GIMP=1，因此如果验证发现上一步的桥接程序仍在响应，就会以该原因失败，而不是借用它。这修复了 2026 年 10 月 15 日的 macOS arm64 实时冒烟测试失败；当时看起来像是 GIMP 崩溃，实际上是验证连接到了正在退出的上一步 GIMP。实时任务不会重试检查：如果 macOS 任务失败，其日志会说明 macOS 是否写入了 GIMP 崩溃报告；macos-gimp-proof-<arch> 工件包含验证报告、GIMP 启动日志和任何崩溃报告。

架构与信任

MCP client → stdio server → authenticated loopback TCP → plug-in inside GIMP

该插件在 GLib 主循环上运行操作，不使用工作线程。它使用每次安装独有的令牌，且只绑定到 127.0.0.1。PDB 调用、配方和 Python 可以使用你的用户权限执行代码：只连接可信客户端。禁用 gimp_run_python 并不构成沙箱。安全性 · 架构

依据 Apache-2.0 协议进行的洁净室实现；未复制其他 GIMP MCP 项目的代码。路线图 · 更新日志 · 报告错误