Gimp Mcp Server

GIMP MCP

演示

完整演示（含音频）：https://github.com/maorcc/gimp-mcp/raw/main/docs/demo.mp4

AI Agent 使用 GIMP MCP 移除背景、编辑角色表情并验证结果——所有操作均通过 Claude 中的自然语言完成

---

概述

GIMP MCP 通过 Model Context Protocol，将 GIMP 的专业图像编辑能力与 AI 助手连接起来。你只需描述想要的效果，就能编辑图像；同时，AI 还可以实时查看图像，验证每项修改后再继续操作。

它与其他 GIMP 集成方案的不同之处：

• AI 可以在工作流的任意阶段查看图像，无需保存到磁盘（get_state_snapshot）
• 支持完全自主的多步骤流水线：打开 → 编辑 → 验证 → 优化 → 导出
• 提供 56 条专用工具命令，涵盖 GIMP 的所有主要操作
• 完全兼容 GIMP 3.2.x（所有不兼容的 API 变更均已解决）

主要功能

👁️ 实时视觉反馈	get_state_snapshot 可在工作流进行中返回 PNG 预览，让 AI 验证每一步
🎨 56 种 GIMP 工具	调整、变换、选区、图层、绘图、文本、滤镜——全部通过 MCP 操作
🔧 兼容 GIMP 3.2	已修复并测试所有 GIMP 3.2 API 变更（56/56 项通过）
🔁 迭代式工作流	AI 会循环执行，直到达成目标——例如持续移除背景，直至没有剩余像素
🖼️ 区域快照	放大任意区域以便详细验证（脸部、嘴巴、角落等）
🔌 通用 MCP	支持 Claude Desktop、Claude Code、Gemini CLI、PydanticAI 等

可以做什么？

通过迭代验证移除背景

AI 移除背景后，会拍摄快照检查结果、检测残留像素，并循环处理，直至图像干净：

"Remove the background from this image and keep looping until only the character remains"

编辑表情

"Make the character smile — paint a smile arc with teeth over her mouth"

复杂的多步骤流水线

"Open navi_portrait.png, remove the background, verify it's clean,
 then make her smile and export the final result as a PNG"

色彩与色调处理

"Boost the contrast, shift the hue 15 degrees warmer, then show me a before/after zoom of the face"

文本与合成

"Add a bold title at the top in white with a subtle drop shadow, then export for web"

---

前置条件

• GIMP 3.2+ — 已在 GIMP 3.2.2 上测试（Windows、macOS、Linux）
• Python 3.8+ — 用于 MCP 服务
• uv — Python 包管理器（pip install uv）
• 兼容 MCP 的 AI 客户端 — Claude Desktop、Claude Code、Gemini CLI、PydanticAI 等

---

快速开始

1. 安装依赖

git clone https://github.com/maorcc/gimp-mcp.git
cd gimp-mcp
uv sync

2. 安装 GIMP 插件

将 gimp-mcp-plugin.py 复制到 GIMP 的 plug-ins 目录，然后重启 GIMP。

目录在哪里？ GIMP 会使用其主版本.次版本号（3.0、3.2、3.4……）命名每个用户的文件夹，并在每次次版本升级时新建文件夹，因此升级 GIMP 时文件夹也会更换（例如 3.0 → 3.2）。下面的代码片段会自动选择最新的文件夹，因此升级后也能继续使用。若要手动查看路径，请打开 GIMP 并进入编辑 → 首选项 → 文件夹 → 插件。

运行此操作前，请至少启动一次 GIMP，以便创建其配置文件夹。

macOS / Linux：

# Pick the base directory for your platform:
BASE="$HOME/Library/Application Support/GIMP"     # macOS
# BASE="$HOME/.config/GIMP"                        # Linux (standard)
# BASE="$HOME/snap/gimp/current/.config/GIMP"      # Linux (Snap)

# Auto-select the newest GIMP 3.x config directory (3.0, 3.2, 3.4, ...):
GIMP_DIR="$(ls -d "$BASE"/3.* 2>/dev/null | sort -V | tail -1)"
if [ -z "$GIMP_DIR" ]; then
  echo "No GIMP 3.x config dir found under $BASE — launch GIMP once, then re-run." >&2
  exit 1
fi
mkdir -p "$GIMP_DIR/plug-ins/gimp-mcp-plugin"
cp gimp-mcp-plugin.py "$GIMP_DIR/plug-ins/gimp-mcp-plugin/"
chmod +x "$GIMP_DIR/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py"
echo "Installed into: $GIMP_DIR/plug-ins/gimp-mcp-plugin"

Windows：

%APPDATA%\GIMP\<VERSION>\plug-ins\gimp-mcp-plugin\gimp-mcp-plugin.py

将 <VERSION> 替换为 GIMP 的主版本.次版本号（例如 3.2）。Windows 上无需 chmod。只需复制并重启 GIMP。

适用于所有平台：GIMP 插件安装指南

3. 在 GIMP 中启动 MCP 服务

1. 在 GIMP 中打开任意图像
2. 前往 工具 > MCP > 启动 MCP 服务
3. 服务将在 localhost:9877 上启动

4. 配置 MCP 客户端

Claude Desktop

~/.config/Claude/claude_desktop_config.json（Linux/macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "gimp": {
      "command": "uv",
      "args": ["run", "--directory", "/full/path/to/gimp-mcp", "gimp_mcp_server.py"]
    }
  }
}

Claude Code

cd /path/to/gimp-mcp
claude  # .mcp.json is auto-detected

或手动配置：

claude mcp add gimp-mcp -- uv run --directory /full/path/to/gimp-mcp gimp_mcp_server.py

Gemini CLI

~/.config/gemini/.gemini_config.json：

{
  "mcpServers": {
    "gimp": {
      "command": "uv",
      "args": ["run", "--directory", "/full/path/to/gimp-mcp", "gimp_mcp_server.py"]
    }
  }
}

PydanticAI

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

server = MCPServerStdio('uv', args=['run', '--directory', '/path/to/gimp-mcp', 'gimp_mcp_server.py'])
agent = Agent('openai:gpt-4o', mcp_servers=[server])

---

可用的 MCP 工具

👁️ 视觉反馈

get_state_snapshot(image_index, max_size, region, label)

返回当前图像状态的实时 PNG——这是 AI 的主要反馈机制。进行任何编辑后都可以调用此工具来验证结果，无需保存到磁盘。

# Full image snapshot
snapshot = get_state_snapshot(max_size=512)

# Zoom into a face region for detail inspection
snapshot = get_state_snapshot(
    region={"x": 140, "y": 80, "width": 240, "height": 300},
    max_size=512,
    label="face-check"
)

这支持迭代式 Agent 工作流：编辑 → 快照 → 评估 → 优化 → 重复。

get_image_bitmap(image_index, max_width, max_height, region)

较低层级的位图获取工具，支持提取区域并缩放。返回 base64 编码的 PNG。

🎨 调整

工具	描述
adjust_brightness_contrast	亮度和对比度
adjust_curves	按通道调整曲线（RGB/R/G/B/A）
adjust_hue_saturation	色相、饱和度、亮度
adjust_color_balance	阴影/中间调/高光色彩平衡
auto_levels	自动拉伸色阶
desaturate	转换为灰度（保留 RGB 模式）
invert_colors	反转所有通道
sharpen	使用反锐化蒙版锐化
blur	高斯模糊
denoise	降噪

🔄 变换

工具	描述
scale_image	缩放到指定尺寸
scale_to_fit	在边界框内缩放（保持纵横比）
crop_to_rect	裁剪为矩形
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	重命名图层
set_layer_properties	不透明度、混合模式、可见性
reorder_layer	调整图层在图层堆栈中的顺序
merge_visible_layers	将可见图层合并为一个图层
flatten_image	合并所有图层
list_layers	列出所有图层及其属性

🖌️ 绘制与填充

工具	描述
fill_layer	用颜色填充整个图层
fill_selection	填充选区（前景色/背景色/透明）
fill_rectangle	填充矩形区域
fill_ellipse	填充椭圆区域
draw_line	绘制线条（铅笔或画笔）
draw_rectangle	绘制矩形轮廓
draw_ellipse	绘制椭圆轮廓
gradient_fill	应用线性或径向渐变
set_colors	设置前景色/背景色

🔤 文本

工具	描述
add_text	添加文本图层
edit_text	编辑现有文本图层
list_fonts	列出可用字体

✨ 滤镜与效果

工具	描述
apply_gaussian_blur	高斯模糊滤镜
apply_pixelate	像素化/马赛克效果
apply_emboss	浮雕效果
apply_vignette	暗角效果
apply_noise	添加噪点/颗粒
apply_drop_shadow	投影效果

📁 文件操作

工具	描述
open_image	打开图像文件
export_image	导出为 PNG、JPEG、BMP、TIFF
new_canvas	创建空白画布
close_image	关闭图像
list_images	列出已打开的图像

🔍 信息与上下文

工具	描述
get_image_metadata	图像尺寸、模式、图层、文件名
get_gimp_info	GIMP 版本、平台、功能
get_context_state	当前颜色、画笔、不透明度、模式
get_pixel_color	特定像素处的颜色值
get_histogram	某个通道的直方图数据
get_selection_bounds	当前选区边界

---

AI Agent 反馈循环

get_state_snapshot 工具支持这样一种模式：AI 持续循环，直到通过视觉确认达成目标：

┌─────────────┐
│  Apply edit │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│ get_state_      │  ← AI sees live PNG, no disk save needed
│ snapshot()      │
└──────┬──────────┘
       │
       ▼
┌─────────────────┐     ┌──────────────────┐
│ Goal achieved?  │─ No─▶ Adjust & retry   │
└──────┬──────────┘     └──────────────────┘
       │ Yes
       ▼
┌─────────────┐
│   Export    │
└─────────────┘

示例：迭代移除背景

完整示例请参见 bg_remove_iterative.py。AI 会：

1. 使用边缘播种的连续选择移除背景
2. 获取快照以检查结果
3. 扫描剩余的背景色像素
4. 使用越来越精细的网格（25px → 1px）执行有针对性的移除
5. 最后执行一次去斑处理，以清除孤立像素
6. 循环处理，直到不再有背景像素

---

示例脚本

脚本	描述
run_tests.py	包含 56 项测试的测试套件 — 在你的 GIMP 中运行，以验证所有工具均可正常工作
bg_remove_iterative.py	通过快照检查点迭代移除背景
bg_remove.py	简单的单次背景移除
agent_edit_demo.py	完整流程：打开 → 移除背景 → 编辑表情 → 导出

运行测试套件以验证你的设置：

python run_tests.py
# Expected: 56/56 PASSED

---

技术架构

插件 ↔ 服务通信

AI Client (Claude, etc.)
      │  MCP (stdio)
      ▼
gimp_mcp_server.py          ← MCP tool definitions
      │  TCP JSON  :9877
      ▼
gimp-mcp-plugin.py          ← Runs inside GIMP process
      │  PyGObject
      ▼
GIMP 3.2 (gi.repository.Gimp)

• MCP 服务将工具调用转换为 JSON 命令，并通过 TCP 发送给插件
• 插件通过 PyGObject 直接在 GIMP 进程中执行操作
• 两种消息格式：命名工具使用 {"type": "...", "params": {...}}，任意执行使用 {"cmds": ["python..."]}

GIMP 3.2 兼容性说明

GIMP 3.x 相较于 GIMP 2.x 引入了不兼容的 API 变更。本版本包含的关键修复：

问题	修复
layer.copy(False) → 错误	GIMP 3.2 中的 layer.copy() 不接受参数
已移除 Gimp.text_fontname()	使用 PDB gimp-text-fontname
已移除 gimp-blend	使用 GEGL gegl:linear-gradient / gegl:radial-gradient
曲线中的 GimpDoubleArray TypeError	直接使用 drawable.curves_spline()
Gimp.fonts_get_list() 返回 Font 对象	在 JSON 序列化前通过 .get_name() 转换
已移除 image.select_none()	使用 PDB gimp-selection-none
layer.get_pixel() 返回 Gegl.Color	使用 .get_rgba() 提取浮点分量

---

故障排除

“无法连接到 GIMP”

• GIMP 必须正在运行，并且已打开图像
• 启动 MCP 服务：工具 > 启动 MCP 服务
• 检查端口 9877 是否被防火墙阻止

在 GIMP 中看不到插件

• 查看 工具 > MCP（该插件会添加一个 MCP 子菜单，而不是顶级 工具 菜单项）
• 确认插件文件位于正确的目录中（参见上文安装步骤）
• 最近升级了 GIMP？ 次要版本升级（例如 3.0 → 3.2）会将每用户配置文件夹移至新的版本目录；请将插件重新安装到新版本的 plug-ins 文件夹中。可通过 编辑 > 首选项 > 文件夹 > 插件 确认当前路径。
• 在 Linux/macOS 上：确保文件具有执行权限（chmod +x）
• 安装后重启 GIMP
• 在 滤镜 > Script-Fu > 控制台 中查看错误消息

测试失败

运行测试套件并检查失败列表：

python run_tests.py

每项失败都会包含工具名称和错误信息 — GIMP 3.2 中的大多数问题都已由上述修复解决。

调试模式

GIMP_MCP_DEBUG=1 uv run --directory /path/to/gimp-mcp gimp_mcp_server.py

---

示例输出

“给我画一张脸和一只羊”——完全通过自然语言，经由 GIMP MCP 生成

---

未来增强

• 📚 配方集：可复用的工作流模板（人像清理、产品照片等）
• ↩️ 撤销系统：通过 MCP 管理历史记录并回滚
• 🚀 动态发现：从 GIMP 的完整 PDB 过程数据库自动生成 MCP 工具
• 🔒 安全性：对不可信的命令输入进行沙箱执行
• ⚡ 性能：优化大图像的位图传输
• 🌐 远程访问：可通过网络访问 GIMP 实例

---

贡献

欢迎贡献——包括修复错误、开发新工具、完善文档或编写示例脚本。请在 GitHub 上提交 PR 或 issue。

开发环境设置

安装开发依赖并启用 pre-commit 钩子，以便每次提交时运行 ruff：

uv sync
uv run pre-commit install

完成后，每次执行 git commit 时，ruff 都会检查暂存文件（并自动应用 --fix）。CI 中也会运行相同的检查，因此该钩子只是一个快速的本地安全网。

之后如需更新固定的钩子版本：

uv run pre-commit autoupdate