GIMP 3 MCP

gimp3-mcp

gimp3-mcp 可让 AI 助手在运行中的 GIMP 3.2 中工作。你描述想要的效果；助手会创建或打开图像、绘画、编辑并导出图像，还会在每个步骤之间查看图像，以检查效果。

它由两部分组成：在 GIMP 中运行的插件，以及由 AI 客户端（Claude Desktop、Claude Code 或其他 MCP 客户端）启动的 MCP 服务。两者协作后，助手便可使用 80 种工具，涵盖笔刷笔触和颜色调整，以及图层、文本和批量导出。

gimp3-mcp 最初是由 maorcc 及其贡献者开发的 gimp-mcp 分支项目，现在则独立开发。请参阅致谢和 gimp3-mcp 与 gimp-mcp 的区别。

---

你可以提出哪些要求

每个示例都是可以发给助手的提示词，后面列出了它通常会使用的工具。

绘制一幅图

Create an 800×800 canvas and paint a ginger cat sitting front-on, in loose painterly strokes.
Look at the canvas after each round of strokes.

new_canvas → 分轮使用 paint_stroke（纹理笔刷、渐细笔触、涂抹）→ 使用 get_state_snapshot 或 preview 选项查看效果 → 使用 sample_color 选取画布上已有的颜色。

修饰照片

Open ~/Pictures/harbor.jpg, auto-level it, add a little contrast and warmth,
sharpen slightly, and export a 2048-pixel-wide JPEG to ~/Pictures/harbor-edit.jpg.

open_image → auto_levels → adjust_brightness_contrast → adjust_color_balance → sharpen → scale_to_fit → export_image。

制作图形

Make a 1200×630 banner with a dark navy background (#1b2a4a) and the title "Summer Sale"
in large white text with a soft drop shadow, then export it for the web.

new_canvas → add_text → apply_drop_shadow → export_web_optimized。

检查细节

Show me the top-left 300×300 pixels of the current image, enlarged.

使用带有 region 的 get_state_snapshot。

处理多张图像

Export every open image as WebP into ~/Desktop/export.

list_images → batch_export。

工具未涵盖的操作

Use GIMP's Python API to list every path in the image and how many strokes each has.

call_api 可在 GIMP 中运行 Python。

工具调用示例

这些调用由助手编写，而不是由你编写；不过，它们能展示工具接受哪些参数。每个代码块都是对应工具的参数。

get_state_snapshot：查看图像的一部分（坐标以图像像素为单位；结果会缩放至适合 max_size 的大小）：

{"image_index": 0, "max_size": 512,
 "region": {"x": 140, "y": 80, "width": 240, "height": 300}}

paint_stroke：绘制一轮笔触并获取预览：

{"preview": true, "strokes": [
  {"points": [[100, 400], [300, 330], [520, 380]], "brush": "Oils 01", "size": 120, "color": "#3b6e8f"},
  {"points": [[140, 420], [300, 370]], "brush": "Bristles 02", "size": 40, "color": "#d9a441", "opacity": 80},
  {"points": [[250, 360], [330, 350]], "tool": "smudge", "size": 50, "pressure": "none", "strength": 40}
]}

call_api：在 GIMP 中运行 Python：

{"api_path": "exec", "args": ["pyGObject-eval", ["len(Gimp.get_images())"]]}

---

工作原理

AI client (Claude Desktop, Claude Code, ...)
      │  MCP over stdio
      ▼
gimp_mcp_server.py        MCP server: tool definitions and descriptions
      │  JSON over TCP, localhost:9877
      ▼
gimp-mcp-plugin.py        GIMP plugin: runs inside GIMP
      │  PyGObject
      ▼
GIMP 3.2

客户端会启动 MCP 服务。服务将每次工具调用转换为 JSON 命令并发送给插件，插件通过 GIMP 的 Python API 执行命令并返回结果。插件一次只运行一条命令。

---

要求

• GIMP 3.2（开发和测试使用的是 macOS 上的 3.2.6）
• uv，它提供 uvx，并会在需要时获取 Python 3.11 或更高版本
• MCP 客户端，例如 Claude Desktop 或 Claude Code

---

安装

1. 安装 GIMP 插件

先启动一次 GIMP，使其创建设置文件夹，然后运行：

uvx gimp3-mcp install-plugin

此命令会将插件复制到 GIMP 设置文件夹中的 plug-ins/gimp-mcp-plugin/，并下载服务，以便 AI 客户端之后能快速启动。它会查找最新的 GIMP 3.x 文件夹：macOS 上为 ~/Library/Application Support/GIMP，Windows 上为 %APPDATA%\GIMP，Linux 上为 ~/.config/GIMP、~/snap/gimp/current/.config/GIMP 和 ~/.var/app/org.gimp.GIMP/config/GIMP。如果 GIMP 将设置保存在其他位置，请传入 --gimp-dir；编辑 > 首选项 > 文件夹 > 插件会显示 GIMP 使用的文件夹。GIMP 会为每个次要版本创建新的设置文件夹，因此升级 GIMP 后请重新运行此命令。安装后重启 GIMP。

2. 在 GIMP 中启动插件的服务器

选择 工具 > MCP > 启动 MCP 服务。无需打开任何图像。服务器会在 localhost:9877 上监听，直到退出 GIMP，因此每次启动 GIMP 后都要再次启动服务器。同一菜单中还有 检查 MCP 服务 和 重启 MCP 服务。

3. 连接 AI 客户端

Claude Desktop。 将服务器添加到 claude_desktop_config.json。在 macOS 上，该文件位于 ~/Library/Application Support/Claude/；在 Windows 上，位于 %APPDATA%\Claude\：

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

退出并重新打开 Claude Desktop。Claude Desktop 允许你单独启用或停用连接器的工具。如果助手说 new_canvas 之类的工具不可用，请在 gimp 连接器的工具设置中启用该工具，然后开始新的聊天。

Claude Code。

claude mcp add --scope user gimp -- uvx gimp3-mcp

其他 MCP 客户端。 将 stdio 服务配置为使用命令 uvx 和参数 gimp3-mcp。

4. 检查连接

让助手“检查 GIMP 连接”。它会调用 check_server，报告插件是否可访问，以及正在运行的 GIMP 版本。

---

工具

服务器提供 80 个工具。每个工具的描述都会向助手说明其参数和结果。

查看图像

工具	功能
get_state_snapshot	获取图像或某个区域的 PNG，并缩放至适合 max_size；这是助手查看图像的主要方式
get_image_bitmap	获取相同的图像数据，并使用单独的 max_width/max_height 和 origin_x/origin_y 区域键
get_image_metadata	图像尺寸、颜色模式、分辨率、图层和文件
sample_color	获取可见图像某个点的颜色，返回十六进制值；也可选择按半径范围取平均
get_pixel_color	获取可见图像或单个图层中某个像素的颜色
get_histogram	获取图层某个通道的均值、中位数和分布范围
get_selection_bounds	获取当前选区的边界框
list_images	按索引顺序列出已打开的图像，包括名称和尺寸
list_layers	从上到下列出图层，并标记活动图层

图像和文件

工具	功能
new_canvas	在新窗口中创建空白图像
open_image	在新窗口中打开图像文件
save_xcf	保存为 GIMP 的 XCF 格式，并保留图层
export_image	导出为 PNG、JPEG、WebP 或 TIFF
close_image	关闭通过 new_canvas 或 open_image 打开的图像（可选择先保存 XCF）
set_active_image	将图像窗口置于最前
convert_color_mode	转换为 RGB、灰度或索引颜色模式

绘画和绘图

工具	功能
paint_stroke	批量绘制笔刷笔画：纹理笔刷、渐细或压力变化笔画、喷枪、涂抹、橡皮擦
list_brushes	列出 paint_stroke 可用的笔刷名称
draw_line	使用铅笔或画笔绘制直线
draw_rectangle / draw_ellipse	绘制矩形或椭圆轮廓
fill_rectangle / fill_ellipse	填充矩形或椭圆
fill_layer	使用某种颜色填充整个图层
fill_selection	使用某种颜色、GIMP 的前景色或背景色、图案或透明度填充选区
gradient_fill	线性或径向渐变
set_colors	设置 GIMP 的前景色和背景色

调整

工具	功能
adjust_brightness_contrast	调整亮度和对比度
adjust_curves	按通道调整曲线，可使用预设或自定义控制点
adjust_hue_saturation	调整所有颜色或某个颜色范围的色相、饱和度和明度
adjust_color_balance	调整阴影、中间调或高光的色彩平衡
auto_levels	自动扩展色调范围
desaturate	将图层转换为灰度
invert_colors	反转图层颜色

滤镜和效果

工具	功能
blur / apply_gaussian_blur	高斯模糊（blur 使用单独的水平和垂直半径）
sharpen	反锐化遮罩
denoise	降噪
apply_noise	添加噪点或颗粒
apply_pixelate	方块马赛克
apply_emboss	浮雕
apply_vignette	加暗边缘
apply_drop_shadow	在图层下方添加柔和的投影
warp_region	已禁用：在 GIMP 3.2 中，该工具会擦除图层而不是扭曲图层，因此现在会返回错误

变换

工具	功能
scale_image	缩放到精确尺寸
scale_to_fit	缩放以适合指定区域，同时保持宽高比
crop_to_rect	裁剪为矩形
crop_to_selection	裁剪到选区，或自动裁剪
rotate_image	旋转 90、180、270 度或任意角度
flip_image	水平或垂直翻转
resize_canvas	更改画布大小，不缩放内容

选区

工具	功能
select_rectangle / select_ellipse	创建矩形或椭圆选区，可选择是否羽化
select_by_color	选择与某种颜色相近的像素
select_all / select_none	全选或取消选择
invert_selection	反选
modify_selection	扩大、收缩、羽化、描边或锐化选区

图层

工具	功能
create_layer	新建空白或填充图层
duplicate_layer	复制图层
delete_layer	删除图层
rename_layer	重命名图层
reorder_layer	在图层堆栈中移动图层
set_layer_properties	设置不透明度、混合模式和可见性
merge_visible_layers	合并可见图层
flatten_image	合并所有图层

文本

工具	功能
add_text	添加文本图层
edit_text	更改文本图层的文本、字体、大小或颜色
list_fonts	列出已安装的字体，可按名称筛选

批处理和导出流程

工具	功能
batch_export	将所有已打开的图像或其中一张导出到文件夹
batch_resize	调整所有已打开图像的大小
export_web_optimized	导出 JPEG 和 PNG，并报告哪种格式的文件更小
export_social_media_kit	导出适用于 Instagram、Twitter/X、Facebook 和 YouTube 的尺寸
export_icon_sizes	导出 Android 或 iOS 图标集
export_sprite_sheet	将图层或已打开的图像合并为精灵图

连接和高级功能

工具	功能
check_server	检查插件是否可访问
restart_server	GIMP 重启后重新连接
get_gimp_info	获取 GIMP 版本、文件夹和环境信息
get_context_state	获取 GIMP 当前的颜色、画笔、不透明度和模式
call_api	在 GIMP 中运行 Python，以实现这些工具未涵盖的功能

该服务还提供两个 MCP 提示词：gimp_best_practices 和 gimp_iterative_workflow。支持提示词的客户端可以将它们添加到对话中。它们也收录于 docs/best_practices.md 和 docs/iterative_workflow.md。

---

工具的行为方式

助手连接时会收到这些规则。阅读它的工具调用或调试结果时，这些规则也很有帮助。

• 图像顺序。 image_index 0 是最近打开或创建的图像；图像打开或关闭时，索引会随之变化。list_images 会显示当前顺序。
• 图层。 带有可选 layer_name 的工具会作用于活动图层。通过 create_layer 或 duplicate_layer 创建的图层会成为活动图层。在 list_layers 中，索引 0 是最上方的图层。
• 颜色。 颜色可以是十六进制格式（"#8b4513"、"#fff"、"#8b451380"），也可以是 16 种基本 CSS 颜色名称之一：black、white、gray、silver、red、maroon、yellow、olive、lime、green、aqua、teal、blue、navy、fuchsia、purple。其他名称和 rgb() 值会被拒绝，因为 GIMP 会将它们转换成错误的颜色。
• 快照。 get_state_snapshot 会缩放图像或区域，使其适合 max_size，因此较小的区域返回时会被放大。区域坐标以图像像素为单位。
• 报错而非猜测。 值有固定列表的选项（例如混合模式、插值或锚点）会拒绝列表以外的值，并在错误中列出有效值。如果 GIMP 无法应用滤镜，滤镜会报错。
• 关闭图像。 close_image 可以关闭通过 new_canvas 或 open_image 打开的图像。GIMP 3 不允许插件关闭从 GIMP 自带菜单打开的窗口；请在 GIMP 中关闭这些窗口。
• 撤销。 没有撤销工具，因为 GIMP 3 不允许插件逐步浏览撤销历史记录。每次工具调用（包括每批 paint_stroke）都是一个步骤，可以在 GIMP 中用 Ctrl+Z 撤销。若要让助手丢弃工作，请让它在单独的图层上绘制，然后删除该图层。

---

安全

插件会通过 call_api 执行收到的任何 Python 代码。服务器运行期间，计算机上任何能够连接到 localhost:9877 的程序都可以控制 GIMP，并以你的用户权限运行代码。插件只接受来自你自己的计算机的连接。需要使用时再启动服务器；退出 GIMP 即可停止服务器。

---

示例脚本

这些脚本无需 AI 客户端，可直接与插件通信。请先在 GIMP 中启动插件的服务器。每个文件的开头都有用法说明。

脚本	功能
bg_remove.py	通过一次模糊选择操作移除背景
bg_remove_iterative.py	通过多次操作移除背景，并在操作之间检查快照
agent_edit_demo.py	打开图像、移除背景、将嘴部扭曲成微笑、检查快照并导出（warp_region 处于禁用状态时，扭曲步骤会失败）

---

故障排除

“无法连接到 GIMP”

• 启动 GIMP，然后选择 Tools > MCP > Start MCP Server。每次重启 GIMP 后都需要重新执行此操作。
• 如果 AI 客户端仍在运行时重启了 GIMP，请让助手运行 restart_server。

GIMP 中缺少 MCP 菜单

• 查看 Tools > MCP。
• 再次运行 uvx gimp3-mcp install-plugin 并重启 GIMP。插件应放在当前 GIMP 版本设置文件夹中的 plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py（Edit > Preferences > Folders > Plug-ins），而 GIMP 每次进行次要版本升级后都会使用一个新文件夹。
• 在 macOS 和 Linux 上，请确保文件具有可执行权限（chmod +x），然后重启 GIMP。
• 插件错误会显示在 GIMP 的 Windows > Dockable Dialogs > Error Console 中。

助手提示工具不存在

• 更新 gimp3-mcp 后，重启 AI 客户端。
• 在 Claude Desktop 中，检查 gimp 连接器的工具设置，确认该工具已启用。

客户端无法启动服务，或提示找不到 uvx

• 从桌面启动的应用不一定能读取 shell 的 PATH。在终端中运行 which uvx，并在配置中填入完整路径，例如 "command": "/usr/local/bin/uvx"。
• 首次启动时会下载软件包。如果客户端因等待超时而放弃，请在终端中运行一次 uvx gimp3-mcp install-plugin，以填充缓存，然后重试。

更改插件后没有效果

• GIMP 会在启动时加载插件。更新 gimp3-mcp 后，运行 uvx gimp3-mcp@latest install-plugin，重启 GIMP 并再次启动服务。uvx 会保留缓存副本，而 @latest 会让它获取最新版本。

---

开发

安装开发依赖和 pre-commit 钩子，该钩子会在每次提交时运行 ruff：

uv sync
uv run pre-commit install

运行与 CI 相同的 lint 检查（版本固定在 .github/workflows/lint.yml 和 .pre-commit-config.yaml 中）：

uvx [email protected] check .

测试会连接到正在运行的 GIMP，因此请先启动插件的服务。测试会创建或打开自己的图像，但 run_tests.py 会编辑最近打开的图像，因此运行前请保存你的工作。

python run_tests.py                   # 85 checks across the tool categories
python tests/test_paint_stroke.py     # paint_stroke, list_brushes, sample_color
python tests/test_add_text_metadata.py

run_tests.py 会更改 GIMP 的前景色和背景色，并保留测试画布处于打开状态。tests/continuous_edit_test/continuous_edit_test.py 会关闭所有已打开的图像，因此不要在有需要保留的工作时运行它。

要从代码库检出目录运行，而不是从 PyPI 运行：

git clone https://github.com/tifyr/gimp3-mcp.git
cd gimp3-mcp
uv sync
uv run gimp3-mcp install-plugin

然后将客户端指向命令 uv，并使用参数 run --directory /full/path/to/gimp3-mcp gimp_mcp_server.py。在该文件夹中启动的 Claude Code 可通过 .mcp.json 提供同一个服务。更改 gimp-mcp-plugin.py 后，运行 uv run gimp3-mcp install-plugin 并重启 GIMP。更改 gimp_mcp_server.py 后，重启 AI 客户端。

要发布，请在 pyproject.toml 和 server.json 中的两处设置新版本，在 CHANGELOG.md 中说明，并推送一个标签，例如 v0.2.0。Release 工作流会检查版本是否一致，然后发布到 PyPI 和 MCP Registry。

---

与 gimp-mcp 的区别

gimp3-mcp 保留了 gimp-mcp 的设计，即 GIMP 插件加 MCP 服务，以及其中的大多数工具。自分叉以来，它新增了：

• 绘画工具： paint_stroke、list_brushes 和 sample_color，可使用 GIMP 自带的画笔进行绘制。
• 修复 GIMP 在 macOS 上冻结的问题： 插件一次只运行一条命令。
• 不再悄无声息地失败： 以前报告成功却什么也没做的工具（如 auto_levels 和 gradient_fill）现在可以正常工作，GIMP 调用失败时也会返回错误。
• 不再破坏已有工作： resize_canvas 会保留图层，close_image 不会覆盖其他文件，工具会保留 GIMP 的颜色和你的选区，而会擦除图层的 warp_region 已被禁用。
• 更可靠的服务： 不再丢失响应，也不会在 GIMP 调用缓慢时卡住每个请求。
• 会检查结果的测试： run_tests.py 会检查像素、颜色和选区，而不仅仅是工具报告的状态。
• 通过 PyPI 安装： 使用 uvx gimp3-mcp，该命令会安装插件。

详情请参阅 CHANGELOG.md。

---

限制

• 必须运行 GIMP 并启动其 MCP 服务（工具 > MCP > 启动 MCP 服务）；gimp3-mcp 无法代你启动 GIMP。
• 本项目基于 macOS 上的 GIMP 3.2.6 开发并测试。Linux 和 Windows 应该也能运行，但尚未针对本次发布进行测试。
• warp_region 已被禁用，因为 GIMP 3.2 没有为插件提供可用的变形操作。
• 插件一次只运行一条命令，因此耗时较长的操作会阻塞下一次调用。
• call_api 会在 GIMP 内运行任意 Python 代码。请参阅安全性。

---

致谢

gimp3-mcp 基于 gimp-mcp，由 maorcc 创建，tomer、jmagdalena、Victor（Viesar Lab）、AnthonyHerman 等人也参与了贡献。插件、服务和大多数工具均来自他们的工作，他们的提交也保留在本仓库的历史记录中。gimp3-mcp 由 tifyr 独立维护，并非 gimp-mcp 的官方版本。

---

许可证

GPL-3.0，与 gimp-mcp 使用相同的许可证。请参阅 LICENSE。