GIMP Studio MCP

GIMP Studio MCP

TwelveTake Studios 的项目。

已在 MCP Registry 登记，名称为 mcp-name: com.twelvetake/gimp-studio-mcp。

GIMP Studio MCP 是一个模型上下文协议服务，可让 AI 助手在 GIMP 3 中编辑图像。每个工具都会返回包含已捕获错误的结构化结果，并可根据请求通过检查点恢复图像的先前状态。它还提供用于印刷和 DTF（直接成膜）转印制作的工具。

13 个组中共有 119 个工具，每个工具都经过真实 GIMP 实例测试。

状态： beta。已在 GIMP 3.2.4 上测试，涵盖无头和实时模式。最高至 0.3.3 的版本也在 GIMP 3.0.4 上测试过。

为什么选择此服务

它专为印刷和 DTF 制作打造：以印刷分辨率设置实际尺寸、去除服装颜色，并输出可用于转印膜的透明 PNG。每个工具都会返回结构化结果，因此助手无需为常规编辑编写 GIMP Python 代码。

设计规则（每个工具均遵循）

1. 结构化返回： { ok, result, stdout, warnings, error }；即使发生错误，也不会丢失输出。
2. 保留原始 exec： 通用应急出口（gimp_exec）仍然可用，并能正确捕获输出。（使用 GIMP_MCP_NO_EXEC=1 选择退出；请参阅安全模型。）
3. 兼容性／特性差异层： 一个模块负责处理 GIMP 3 的差异和已知问题。
4. 与模式无关的工具： 无论 GIMP 处于实时模式（画布可见）还是无头模式，工具的工作方式都相同。
5. 视觉优先： get_bitmap 会返回 Agent 实际可查看的图像（可指定区域、缩放比例和字节预算），用于自我验证。
6. 默认安全： 对破坏性操作使用 checkpoint / restore。
7. 全面验证参数。
8. 贯穿始终地考虑印刷需求： DPI／英寸是一级参数；DTF 输出是核心功能。

架构（从第一天起采用混合模式）

实时模式和无头模式的差异仅在于由谁启动 GIMP，而不在于我们如何与它通信——因此只需一个桥接程序：

• 实时模式： 持久运行的 GIMP 扩展（通过 gimp-mcp install-plugin 安装）会在启动时运行并发布一个本地回环端点；MCP 服务会自动连接到正在运行的 GIMP，画布保持可见。
• 无头模式： 如果未检测到实时运行的 GIMP，服务会启动一个长期运行的 gimp -i，并加载同一个桥接程序。

两种模式都使用同一种基于本地回环 TCP、长度前缀 JSON 和令牌认证的协议；两种模式均支持像素导出。

功能领域（119 个工具）

分组	工具数	涵盖内容
会话	5	健康状态／状态信息、打开的图像列表、切换活动图像、原始 gimp_exec、重置命名空间
文档	4	新建／打开图像、元数据、保留透明度的安全导出
图层	18	创建／复制／删除／重新排序／移动、不透明度、混合模式、组、合并、内容偏移与接缝检查（可平铺纹理）
蒙版与 Alpha	9	添加／应用／移除蒙版、添加／锁定 Alpha、Alpha↔选区、亮度→Alpha、颜色→Alpha（柔和）以及 cutout_color（清晰的硬边抠除）
选区	15	矩形／椭圆／按颜色／模糊／从路径／从 Alpha 创建选区、扩展／收缩／羽化／边框、反转、转为通道、foreground_select（具备边缘感知的主体抠取／遮罩）
绘画	10	铅笔／画笔、桶填充、渐变、描边、前景／背景色与画笔及不透明度上下文
文本	5	创建／编辑文本图层、属性、轮廓、字体检查／替换
颜色与色调	10	亮度／对比度、色阶、曲线、色相／饱和度、色彩平衡、去色、色调分离、反相、阈值、标准化（自动拉伸对比度）
滤镜与效果	4	高斯模糊、锐化蒙版、投影、通用 GEGL apply_filter
印刷／DTF	13	白色底层、边缘内缩／扩展、裁切至内容、knockout_background（感知服装颜色）、DTF 清理、半色调分色、拼版（22″@300）、DTF PNG 导出、几何／出血
色彩管理	7	指定／转换 ICC 配置文件、灰度／RGB 转换、配置文件检查
分析	12	get_bitmap（可查看的预览）、直方图（感知型，与 levels 匹配）、取色、区域读取、元数据、操作说明、GEGL／过程列表
安全	7	检查点／恢复（可脚本化回滚）、撤销组、检查点列表

工具可通过 MCP 客户端自我描述；describe_op 和 list_* 工具会在运行时列出操作和资源。

要求

• GIMP 3.x（已在 3.2.4 上测试）
• Python 3.10+（用于 MCP 服务）
• 兼容 MCP 的 AI 助手（例如 Claude Code / Claude Desktop）

安装

1. 安装服务

从 PyPI 安装：

pipx install twelvetake-gimp-studio-mcp

或从克隆的仓库安装：

git clone https://github.com/TwelveTake-Studios/gimp-studio-mcp
cd gimp-studio-mcp
pip install -e .

2. 安装 GIMP 端桥接程序

gimp-mcp install-plugin     # copies the bridge into GIMP's plug-ins dir
gimp-mcp doctor             # verify install + GIMP exe + bridge reachability

重启 GIMP（或在下次启动时加载）。该桥接程序会作为持久扩展自动启动。

3. 在 MCP 客户端中注册

将以下内容添加到客户端的 MCP 配置中（例如 .mcp.json）：

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

如果有正在运行的 GIMP，服务会连接到它；否则会自动启动无头 GIMP。设置 GIMP_MCP_HEADLESS=1 可始终以无头模式运行。

快速入门

常规编辑

"Open logo.png and tell me its size and layers"
"Add a 12px white outline to the text layer"
"Auto-crop the image to its content, then export a transparent PNG"
"Show me the current canvas"          → get_bitmap returns a viewable preview

DTF（直接制版印花）——核心工作流

"Knock out the black shirt color behind this artwork"     → knockout_background, garment-aware
"Add a white underbase choked 2px so it doesn't peek"      → white_underbase + edge_choke
"Clean this up for DTF and export a 300-DPI transparent PNG"
"Gang up 12 copies of this design onto a 22-inch sheet at 300 DPI"

knockout_background 会感知服装颜色：传入 shirt= 预设（black、navy、heather_gray、red 等），它会选择合适的移除方式（深色服装使用颜色转 Alpha，因为显示出来的黑色就是衬衫本身；浅色／高饱和度服装则使用硬边选区并清除）。list_shirt_presets 可查看预设目录。

安全模型

此服务运行在与本地用户相同的信任边界内。安装后，任何已连接的 AI Agent 都能控制你机器上的 GIMP，并可通过 gimp_exec 在 GIMP 进程中运行任意 Python 代码。这是为单用户工作站设计的；它不是沙箱。

• 仅限环回地址 + 令牌。 桥接程序会在 127.0.0.1 上监听，使用临时端口和每会话令牌。它不会暴露到网络。
• gimp_exec 按设计可执行任意主机代码。 恶意指令或提示词注入指令（例如隐藏在你要求 Agent 打开的图像中）可能会调用 gimp_exec。请仅连接可信的 Agent，并使用可信内容。
• 禁用开关。 设置 GIMP_MCP_NO_EXEC=1 可完全跳过 gimp_exec 的注册；其余 118 个结构化工具仍可使用。

完整的威胁模型和报告说明请参阅 SECURITY.md。

环境变量

变量	效果
GIMP_MCP_HEADLESS	始终运行无头 GIMP（启动 gimp -i），而不是连接到正在运行的实例（1/true/yes/on）。
GIMP_MCP_NO_EXEC	跳过注册原始的 gimp_exec 主机代码执行工具（1/true/yes/on）。
GIMP_MCP_DISABLED	GIMP 内部桥接程序会确认收到请求，但不提供服务。
GIMP_MCP_ENDPOINT_FILE	指定端点文件路径（高级用法／无头模式）。
GIMP_MCP_PORT	固定桥接端口，而不是使用临时端口。
GIMP_MCP_EXE	GIMP 的 gimp-console 可执行文件路径，用于服务器无法自动找到 GIMP 的安装。
GIMP3_DIRECTORY	GIMP 自有变量，用于指定非默认的 GIMP 配置文件夹。gimp-mcp install-plugin 会在该文件夹中安装桥接程序，gimp-mcp doctor 也会检查该文件夹。
GIMP_MCP_OPERATION_TIMEOUT	单个 GIMP 操作运行到超时错误前可持续的秒数（默认值为 120）。
GIMP_MCP_START_TIMEOUT	等待无头 GIMP 启动的秒数（默认值为 60）。
GIMP_MCP_CONNECT_TIMEOUT	连接 GIMP 时的等待秒数（默认值为 10）。

故障排除

先运行 gimp-mcp doctor——它会检查安装情况、定位 GIMP 可执行文件，并对桥接程序进行往返测试。添加 --headless 还会启动无头 GIMP 并验证完整的往返流程。

• GIMP 已打开，但提示“Bridge not reachable”： 确认已运行 gimp-mcp install-plugin，并重启 GIMP，以便加载桥接扩展。
• 修改了服务器，但工具看起来没有变化： MCP 服务不会热重载——请重启 MCP 客户端会话。

许可证

MIT — 详见 LICENSE。

---

TwelveTake Studios LLC 网站：twelvetake.com 联系邮箱：[email protected]