GIMP-MCP服务器

Name: GIMP-MCP服务器
Author: maorcc

作者：maorcc25 星标更新：2025-10-29

安装使用来源：spider==github.com

项目介绍

GIMP MCP

概述

该项目使非技术人员能够通过简单的对话命令使用GIMP编辑图像，弥合了GIMP的强大功能与自然语言交互之间的差距。它还允许专业人士比传统的点击操作更快地执行复杂的多步骤工作流程。

用户可以描述他们想要实现的目标——从基本的照片调整到复杂的艺术修改。例如，“提亮背景并添加复古滤镜”或“去除红眼并锐化主题”——系统会将这些请求转换为精确的GIMP操作。

该项目完全可用，并通过MCP（模型上下文协议）暴露所有GIMP功能。新功能：符合MCP标准的图像导出，允许像Claude这样的AI助手直接查看和分析您的GIMP图像！

主要特性

✨ 符合MCP标准的图像导出：AI助手可以直接查看图像
🎨 完整的GIMP 3.0 API访问：通过PyGObject执行任何GIMP操作
🔧 多种格式导出：PNG、JPEG、BMP、TIFF，带有质量控制
📊 图像元数据：获取图像信息而不传输数据
🛡️ 强大的错误处理：多个备用方法以确保可靠性
🔌 通用MCP支持：适用于Claude Desktop、Gemini CLI、PydanticAI等

预备条件

GIMP 3.0及以上版本：此项目是基于GIMP 3.0开发和测试的。早期版本不被支持。
兼容MCP的AI客户端：Claude Desktop、Gemini CLI、PydanticAI或其他MCP客户端。
Python 3.8+：MCP服务器所需。
uv：一个现代的Python包安装器和解析器。

快速开始

1. 安装依赖项

# 克隆仓库
git clone https://github.com/maorcc/gimp-mcp.git
cd gimp-mcp

# 安装Python依赖项
uv sync

2. 安装GIMP插件

将gimp-mcp-plugin.py复制到您的GIMP plug-ins目录中，并使其可执行。

快速安装（Linux）：

# 对于标准GIMP安装
mkdir -p ~/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin
cp gimp-mcp-plugin.py ~/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin/
chmod +x ~/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py

# 对于Snap安装的GIMP
mkdir -p ~/snap/gimp/current/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin
cp gimp-mcp-plugin.py ~/snap/gimp/current/.config/GIMP/3.0/plug-ins/gimp-mcp-plugin/
chmod +

快速安装（macOS）：

mkdir -p ~/Library/Application\ Support/GIMP/3.0/plug-ins/gimp-mcp-plugin
cp gimp-mcp-plugin.py ~/Library/Application\ Support/GIMP/3.0/plug-ins/gimp-mcp-plugin/
chmod +x ~/Library/Application\ Support/GIMP/3.0/plug-ins/gimp-mcp-plugin/gimp-mcp-plugin.py

手动安装：

有关在不同操作系统上定位GIMP插件文件夹的详细说明，请参阅以下指南：

GIMP插件安装指南（Wikibooks）

确保插件文件具有“执行”权限。

安装后重启GIMP。

3. 在GIMP中启动MCP服务器

在GIMP中打开任意图像
导航至工具 > 启动MCP服务器
服务器将在localhost:9877启动

4. 配置您的MCP客户端

Claude Desktop

在您的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"
      ]
    }
  }
}

Gemini CLI

在~/.config/gemini/.gemini_config.json中配置您的Gemini CLI MCP服务器：

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

PydanticAI

对于PydanticAI代理，使用MCPServerStdio类：

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

server = MCPServerStdio(
    'uv',
    args=[
        'run',
        '--directory',
        '/full/path/to/gimp-mcp',
        'gimp_mcp_server.py'
    ]
)

agent = Agent('openai:gpt-4o', mcp_servers=[server])

其他MCP客户端

对于支持stdio传输的其他MCP客户端，使用以下命令：

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

使用示例

基本用法

启动GIMP并打开任意图像
启动MCP服务器：工具 > 启动MCP服务器
启动您的MCP客户端（如Claude Desktop）
开始创建：“用GIMP画一张脸和一只羊”

高级功能

图像分析

“你能展示一下当前GIMP中的图像并告诉我你看到了什么吗？”

使用get_image_bitmap()检索并分析当前画布

快速图像信息

“当前图像的尺寸和属性是什么？”

使用get_image_metadata()快速获取图像信息而不传输位图数据

智能工作流决策

“检查当前图像是否有透明度和多层，然后再应用效果”

使用get_image_metadata()分析图像结构进行智能决策

环境发现

“我正在使用的GIMP版本是什么，有哪些可用的功能？”

使用get_gimp_info()提供全面的环境信息以获得最佳支持

故障排除支持

“我在插件导出方面遇到了问题——检查我的GIMP设置并提出解决方案”

使用get_gimp_info()诊断安装和配置问题

复杂的工作流

“创建一个新的800x600图像，在中心画一个蓝色圆圈，添加红色边框，然后显示结果”

结合多个GIMP操作和图像导出进行验证

可用的MCP工具

GIMP MCP服务器提供了几个AI助手可以使用的工具：

🖼️ 图像导出工具

get_image_bitmap()

返回当前图像作为base64编码的PNG位图，支持区域提取和缩放。

参数：

max_width（可选）：全图缩放的最大宽度
max_height（可选）：全图缩放的最大高度
region（可选）：用于区域提取的字典，键包括：
- origin_x：区域左上角的X坐标
- origin_y：区域左上角的Y坐标
- width：要提取的区域宽度
- height：要提取的区域高度
- max_width：区域缩放的最大宽度（可选）
- max_height：区域缩放的最大高度（可选）

使用示例：

# 获取全图位图
result = await client.get_image_bitmap()

# 将全图缩放到最大800x600（保持宽高比）
result = await client.get_image_bitmap(max_width=800, max_height=600)

# 提取区域（100,100），大小400x300
result = await client.get_image_bitmap(
    region={"origin_x": 100, "origin_y": 100, "width": 400, "height": 300}
)

# 提取区域并将其缩放到200x150（保持宽高比）
result = await client.get_image_bitmap(
    region={
        "origin_x": 100, "origin_y": 100, "width": 400, "height": 300,
        "max_width": 200, "max_height": 150
    }
)

if result['status'] == 'success':
    image_data = result['results']['image_data']  # base64编码的PNG
    width = result['results']['width']
    height = result['results']['height']
    original_width = result['results']['original_width']
    original_height = result['results']['original_height']
    processing = result['results']['processing_applied']

- **`get_image_metadata()`**：获取全面的图像元数据而不传输位图数据（快速）

### 🔍 系统信息工具
- **`get_gimp_info()`**：获取全面的GIMP安装和环境信息
- **`get_context_state()`**：获取当前GIMP上下文状态（颜色、画笔、羽化、不透明度）

返回当前GIMP上下文状态，包括前景/背景颜色、画笔、不透明度、绘画模式、羽化设置和抗锯齿状态。

### 🔧 API访问工具  
- **`call_api(api_path, args, kwargs)`**：执行任何GIMP 3.0 PyGObject命令

### 🎨 常见可用操作
- 创建新的图像和图层
- 绘制形状、线条和曲线
- 应用滤镜和效果
- 调整颜色和亮度
- 添加文本和选择
- 在图像之间复制/粘贴
- 以各种格式导出

详细的API文档，请参阅[GIMP_MCP_PROTOCOL.md](GIMP_MCP_PROTOCOL.md)。

## 技术架构

### MCP合规性
- **图像内容**：返回带有base64数据和MIME类型的`ImageContent`对象
- **错误处理**：使用MCP标准异常传播
- **工具元数据**：全面的工具描述和参数模式
- **协议版本**：兼容MCP规范2025-06-18

### GIMP 3.0集成
- **PyGObject API**：直接访问GIMP的Python绑定
- **持久上下文**：命令执行在调用间保持状态
- **可靠的导出**：多个备用方法以确保可靠的图像导出
- **实时更新**：立即刷新显示，使用`Gimp.displays_flush()`

## 故障排除

### 常见问题

#### “无法连接到GIMP”
- 确保GIMP正在运行且有打开的图像
- 验证MCP服务器已启动（工具 > 启动MCP服务器）
- 检查端口9877是否未被防火墙阻止

#### 导出错误
- 插件包括多个备用导出方法
- 支持各种GIMP 3.0 API版本
- 自动处理缺失的导出过程

#### 插件不可见
- 验证插件位于正确的目录并具有执行权限
- 安装后重启GIMP
- 检查GIMP的错误控制台以查找插件加载问题

### 调试模式
添加调试日志以查看详细的MCP通信：
```bash
GIMP_MCP_DEBUG=1 uv run --directory /path/to/gimp-mcp gimp_mcp_server.py

示例输出

来自提示“画一张脸和一只羊”的GIMP MCP示例输出

未来改进

我们欢迎贡献！以下是改进的一些领域：

计划功能

📚 配方集合：常见的GIMP工作流程作为可重用的MCP工具
↩️ 回滚系统：历史管理和回滚能力
🔍 视觉反馈：增强的进度指示器和操作预览
🚀 动态发现：自动从GIMP的过程数据库生成MCP工具
📝 增强错误：带建议修复的上下文感知错误消息
🛡️ 资源管理：插件中的更好清理和错误恢复

架构改进

🔒 安全：用户命令的沙箱执行环境
⚡ 性能：优化大型文件的图像传输
🌐 远程访问：支持网络可访问的GIMP实例
📊 分析：使用指标和性能监控

贡献

欢迎贡献！无论是bug修复、新功能还是文档改进，都可以自由提交Pull Request或打开问题。