内容
# gimp-mcp
[](https://www.python.org/downloads/)
[](pyproject.toml)
[](https://modelcontextprotocol.io)
[](LICENSE)
[](https://github.com/mergeos-bounties)
**gimp-mcp** 是一个 MCP 服务器，用于驱动 **GIMP 风格的图片操作**：打开/创建图片，调整大小，裁剪，翻转，旋转，模糊，去除饱和度，文本叠加，导出和批量调整大小。
| 模式 | 后端 | 何时 |
| --- | --- | --- |
| **模拟** （默认） | Pillow | CI，离线，无 GIMP 安装 |
| **实时** | `gimp-console` 批处理 + Pillow 辅助 | 安装有 GIMP 2.10 / 3.x 的机器 |
**产品：** [mergeos-bounties/gimp-mcp](https://github.com/mergeos-bounties/gimp-mcp) · 资助： **`prj_0525`**
---
## 安装（一条命令）
### Grok — 推荐
```bash
pip install "git+https://github.com/mergeos-bounties/gimp-mcp.git" && grok plugin install mergeos-bounties/gimp-mcp --trust
```
这会安装 **Python CLI** （`gimp-mcp`）和 **Grok 插件** （技能 + MCP 服务器来自 `.mcp.json`）。
检查：
```bash
gimp-mcp version
gimp-mcp doctor
gimp-mcp demo
grok plugin list
grok mcp list
```
本地克隆：
```bash
git clone https://github.com/mergeos-bounties/gimp-mcp.git
cd gimp-mcp
pip install -e ".[dev]"
grok plugin install . --trust
```
### 其他代理（stdio MCP）
在 `pip install "git+https://github.com/mergeos-bounties/gimp-mcp.git"` 之后，将任何 MCP 主机指向：
| 字段 | 值 |
| --- | --- |
| 命令 | `gimp-mcp` |
| 参数 | `["serve"]` |
| 环境变量 | `GIMP_MCP_MODE=mock` |
**Claude Desktop** — 将 [examples/claude_desktop_config.json](examples/claude_desktop_config.json) 合并到 Claude MCP 配置中。
**Cursor** — 将 [examples/cursor_mcp.json](examples/cursor_mcp.json) 合并到 Cursor MCP 配置中。
**Grok config.toml** （手动，无插件）：
```toml
[mcp_servers.gimp_mcp]
command = "gimp-mcp"
args = ["serve"]
env = { GIMP_MCP_MODE = "mock" }
enabled = true
```
**通过 Grok CLI 一行命令：**
```bash
pip install "git+https://github.com/mergeos-bounties/gimp-mcp.git"
grok mcp add gimp-mcp -- gimp-mcp serve
```
## 支持的 AI 代理 / 主机
| 主机 | 支持 | 安装 |
| --- | --- | --- |
| **Grok** （CLI / TUI / 构建） | **是** | `grok plugin install mergeos-bounties/gimp-mcp --trust` 然后 `pip install "git+https://github.com/mergeos-bounties/gimp-mcp.git"` |
| **Claude Desktop** | **是** | 将 [examples/claude_desktop_config.json](examples/claude_desktop_config.json) 复制到 Claude MCP 设置中 |
| **Cursor** | **是** | 将 [examples/cursor_mcp.json](examples/cursor_mcp.json) 合并到 Cursor MCP 配置中 |
| **Claude Code** | **是** | stdio MCP：与 Claude Desktop / Grok 相同的 `command`/`args` |
| **VS Code** （MCP / Continue / Cline） | **是** | 指向 `gimp-mcp serve` 的通用 stdio 服务器配置 |
| **Windsurf / Cascade** | **是** | 带有 `gimp-mcp` + `serve` 的 stdio MCP 条目 |
| **Codex CLI** | **是** （stdio） | 在 Codex MCP 设置中注册 MCP 服务器命令 `gimp-mcp serve` |
| **ChatGPT Desktop** | **部分** | 仅当主机支持自定义 MCP stdio 服务器 |
| **Gemini CLI** | **部分** | 仅当启用 MCP stdio 插件 |
所有软件包都通过 **stdio** 说话 （`gimp-mcp serve`）。默认模式是 **模拟** （离线，无模拟器/终端/GIMP）。
---
## 亮点
| 能力 | 描述 |
| --- | --- |
| **MCP 工具** | `gimp_doctor`, `gimp_open`, `gimp_resize`, `gimp_export`, … |
| **CLI** | `gimp-mcp demo`, `doctor`, `live-smoke`, `serve`, `call` |
| **离线演示** | 始终与 Pillow 模拟一起工作 |
| **实时 GIMP 3** | `python-fu-eval` + `--quit` （~2s 规模在 Windows 上） |
| **实时 GIMP 2** | Script-Fu 批处理 |
| **Grok 插件** | `skills/gimp-mcp` + `.mcp.json` + `.grok-plugin/plugin.json` |
---
## 快速开始（开发者）
```powershell
cd mcp\GIMP-mcp
pip install -e ".[dev]"
gimp-mcp version
gimp-mcp doctor
gimp-mcp demo
pytest -q
```
### 实时 GIMP（可选）
```powershell
# 安装 GIMP 3.x，然后：
$env:GIMP_MCP_MODE = "live"
# 可选覆盖：
# $env:GIMP_MCP_BIN = "$env:LOCALAPPDATA\Programs\GIMP 3\bin\gimp-console.exe"
gimp-mcp doctor
gimp-mcp live-smoke
```
### MCP 主机配置
插件附带 [`.mcp.json`](.mcp.json)。手动示例： [examples/claude_desktop_config.json](examples/claude_desktop_config.json)， [examples/cursor_mcp.json](examples/cursor_mcp.json).
```json
{
"mcpServers": {
"gimp-mcp": {
"command": "gimp-mcp",
"args": ["serve"],
"env": { "GIMP_MCP_MODE": "live" }
}
}
}
```
---
## CLI / 工具
| 命令 | 用途 |
| --- | --- |
| `gimp-mcp version` | 软件包 + 检测到的控制台 |
| `gimp-mcp doctor` | 后端健康 |
| `gimp-mcp demo` | 模拟端到端烟雾测试 |
| `gimp-mcp live-smoke` | 实时控制台烟雾测试（跳过如果丢失） |
| `gimp-mcp tools list` | MCP 工具名称 |
| `gimp-mcp call …` | 一次性工具（`key=value`） |
| `gimp-mcp process <image>` | 完整的真实照片管道 → 多个导出 |
| `gimp-mcp serve` | Stdio MCP 服务器 |
### 真实照片
```powershell
$env:GIMP_MCP_MODE = "live"
gimp-mcp process "C:\path\to\photo.jpg" --out-dir ".\examples\real-run" --watermark "MergeOS"
```
写入 `*_processed.png`， `*_gray.png`， `*_crop_flip_*.png` 和 `batch_thumbs/` （GIMP 3 规模通过 python-fu-eval）。
MCP 工具： `gimp_mode`, `gimp_doctor`, `gimp_seed_demo`, `gimp_list_images`, `gimp_close`, `gimp_new_image`, `gimp_open`, `gimp_info`, `gimp_resize`, `gimp_thumbnail`, `gimp_crop`, `gimp_flip`, `gimp_rotate`, `gimp_blur`, `gimp_sharpen`, `gimp_desaturate`, `gimp_invert`, `gimp_brightness`, `gimp_contrast`, `gimp_auto_orient`, `gimp_text_overlay`, `gimp_pipeline`, `gimp_export`, `gimp_batch_resize`.
环境变量：
| 变量 | 含义 |
| --- | --- |
| `GIMP_MCP_MODE` | `mock` （默认）或 `live` |
| `GIMP_MCP_BIN` | `gimp-console` 的路径 |
| `GIMP_MCP_WORKSPACE` | 临时图片的工作目录 |
| `GIMP_MCP_TIMEOUT` | 批处理超时秒数 |
---
## 文档
| 文档 | 内容 |
| --- | -------- |
| [docs/GIMP_VERSIONS.md](docs/GIMP_VERSIONS.md) | GIMP 2.10 vs 3.x 批处理 CLI 矩阵，GIMP_MCP_BIN 发现，迁移指南 |
| [docs/GIMP_BATCH_FLAGS.md](docs/GIMP_BATCH_FLAGS.md) | 原始批处理标志快速参考 |
| [docs/BOUNTY.md](docs/BOUNTY.md) | MergeOS 悬赏信息 |
---
## 开发
```powershell
pip install -e ".[dev]"
ruff check src tests
pytest -q
```
插件布局：
```
.grok-plugin/plugin.json # Grok 插件清单
.mcp.json # MCP stdio 服务器用于 Grok
skills/gimp-mcp/ # 技能（自动加载安装后）
.grok/skills/gimp-mcp/ # 相同的技能用于存储库发现
```
---
## MergeOS 悬赏任务
**关注** [mergeos-bounties](https://github.com/mergeos-bounties) + **星标** [mergeos](https://github.com/mergeos-bounties/mergeos) 和 [mergeos-contracts](https://github.com/mergeos-bounties/mergeos-contracts)。认领问题 → PR 到 **master** → **25–200 MRG**。
参见 [docs/BOUNTY.md](docs/BOUNTY.md)。
---
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
## 实时测试说明（维护者）
在 Windows 上使用 GIMP **3.2.4** 验证
`%LOCALAPPDATA%\Programs\GIMP 3\bin\gimp-console.exe`
- 实时调整大小使用 **python-fu-eval** + `--quit` （不是 Script-Fu 挂起）
- `gimp-mcp live-smoke` 在几秒内完成
- 过滤器可能仍按设计使用 Pillow 辅助
