AI导哈

AI图像编辑工具

GIMP MCP是一款通过自然语言驱动AI进行专业图像编辑的工具，支持实时视觉反馈和多步骤工作流。

  • by maorcc
  • Python
  • 本地部署
  • 279 星标
  • 更新于
在 GitHub 查看 maorcc/gimp-mcp

使用说明

GIMP MCP

演示

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

AI代理使用GIMP MCP删除背景、编辑角色的表情并验证结果——所有这些都是通过Claude的自然语言完成的

概述

GIMP MCP通过以下方式将GIMP的专业图像编辑功能与AI助手连接起来 模型上下文协议它允许你通过描述你想要的内容来编辑图像，并为人工智能提供了一个实时的视觉反馈渠道，以便在继续之前验证每一个变化。

它与其他GIMP集成有何不同：

  • AI可以 看见 在工作流中的任何点保存图像，而不保存到磁盘(get_state_snapshot)
  • 支持完全自主的多步管道：开放式→ edit → 验证→ 精炼→ 出口
  • 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循环直到达到目标——例如，不断删除BG，直到没有像素为止
🖼️ 区域快照 放大任何区域进行细节验证（面部、嘴部、角落等）
🔌 通用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"

先决条件

  • 万向节3.2+ --在GIMP 3.2.2（Windows、macOS、Linux）上测试
  • Python 3.8+ --对于MCP服务器
  • 紫外线 --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的插件目录并重新启动GIMP。

哪个目录？ GIMP将其每个用户文件夹命名为 多数人.少数人 版本 (3.0, 3.2, 3.4，…）并在每次小升级时创建一个新的文件夹，因此该文件夹 移动 升级GIMP时（例如。 3.0 → 3.2).下面的代码段会自动选择 最新版本，因此它在升级过程中仍能正常工作。要手动检查路径，请打开GIMP 看看 Edit → 偏好→ 文件夹→ 插件.

在运行此程序之前，请至少启动一次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"

窗户：

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

替换 <VERSION> 与您的GIMP major.minor（例如。 3.2).Windows上不需要chmod。只需复制并重新启动GIMP。

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

3.在GIMP中启动MCP服务器

  1. 在GIMP中打开任何图像
  2. 首选 工具>MCP>启动MCP服务器
  3. 服务器启动于 localhost:9877

4.配置您的MCP客户端

克劳德桌面

~/.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"]
    }
  }
}

克劳德代码

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

双子星命令行工具

~/.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"
)

这实现了迭代代理工作流： edit → 快照→ 评估→ 精炼→ 重复.

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代理反馈循环

这 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
bg_remove.py 简单的单程背景去除
agent_edit_demo.py 满管道：打开→ 删除BG→ 编辑表达式→ 出口

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

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..."]} 用于任意exec

GIMP 3.2兼容性说明

GIMP 3.x从GIMP 2.x引入了突破性的API更改。此版本中包含的关键修复程序：

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

故障排除

“无法连接到GIMP”

  • GIMP必须在图像打开的情况下运行
  • 启动MCP服务器： 工具>启动MCP服务器
  • 检查端口9877是否未被防火墙阻止

插件在GIMP中不可见

  • 看下面 工具>MCP （插件添加了一个 MCP 子菜单，而非顶层 Tools 条目）
  • 确认插件文件在正确的目录中（请参阅上面的安装步骤）
  • 最近升级了GIMP？ 小幅升级（例如3.0→ 3.2) 将每个用户的配置文件夹移动到新的版本目录；将插件重新安装到新版本中 plug-ins 文件夹。通过验证活动路径 编辑>首选项>文件夹>插件.
  • 在Linux/macOS上：确保文件具有执行权限(chmod +x)
  • 安装后重新启动GIMP
  • 检查 过滤器>脚本功能>控制台 用于错误消息

测试失败

运行测试套件并检查故障列表：

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实例

贡献

欢迎贡献——bug修复、新工具、文档或示例脚本。在GitHub上打开PR或问题。

开发设置

安装开发依赖项并激活预提交挂钩，以便 ruff 在每次提交时运行：

uv sync
uv run pre-commit install

在此之后， ruff 检查每个上的暂存文件 git commit （与 --fix 自动应用）。同样的检查在CI中运行，因此钩子只是一个快速的本地安全网。

要稍后碰撞固定钩版本，请执行以下操作：

uv run pre-commit autoupdate

相关 MCP