内容
# comfyui-flux2-mcp
一个 [MCP](https://modelcontextprotocol.io)（模型上下文协议）服务器，允许 **Claude** 在您自己的机器上通过本地 **ComfyUI** + **FLUX.2 Klein 9B** 安装来生成和编辑图像。
注册后，您可以在任何Claude Code对话中说类似的话 *"生成一只飞行中的蜂鸟图像"*。Claude 调用此服务器，图像在您的GPU上渲染，您将收到保存的PNG文件的路径。编辑方式相同： *"编辑 `C:/photos/garden.jpg` — 让它看起来像秋天"*。
无需云GPU租赁。无需API成本。您的提示和输出永远不会离开您的机器。
## 工具列表
服务器在MCP下注册为 **`comfyui-flux2`**，并暴露两个工具：
| 工具 | 签名 | 用途 |
|---|---|---|
| `generate_image` | `(prompt, width=1024, height=1024, seed=-1)` | 使用FLUX.2 Klein 9B进行文本转图像。宽度/高度必须是16的倍数。`seed=-1` 每次调用都会随机化。返回保存的PNG文件的绝对路径。 |
| `edit_image` | `(source_path, prompt, seed=-1)` | 类似上下文的图像编辑 — 源图像成为潜在参考，提示是指令编辑（例如 *"让它变成夜间"*， *"添加雪"*）。返回编辑后的PNG文件的绝对路径。 |
## 架构
一个故意精简的堆栈 — 三个小模块，没有官方MCP SDK之外的框架：
```
Claude (任何MCP客户端)
│ stdio (JSON-RPC via FastMCP)
▼
src/server.py — 工具定义；加载工作流模板，
│ 根据调用修补提示/大小/种子/模型文件名
▼
src/comfy_client.py — ComfyUI的HTTP API的薄包装：
│ 发布/prompt以提交，轮询GET /history/<id>
│ 每3秒直到成功/错误/超时
▼
ComfyUI (本地，默认http://127.0.0.1:8188)
└─ 在COMFYUI_OUTPUT_DIR/mcp/下保存PNG
```
- **`src/templates/t2i.json`** — API格式的文本转图像工作流： `UnetLoaderGGUF → CLIPTextEncode (Qwen3) → Flux2Scheduler → SamplerCustomAdvanced → VAEDecode → SaveImage`。
- **`src/templates/edit.json`** — 编辑工作流：源图像复制到ComfyUI的 `input/` 下一个唯一的临时名称， `VAEEncode`，并作为 `ReferenceLatent` 注入指令提示（临时复制在运行后清理）。
- **`src/config.py`** — 所有配置来自 `.env` （使用 `python-dotenv` 加载）；模型/CLIP/VAE文件名在调用时修补到模板中，因此交换FLUX.2变体不需要代码更改。
- 依赖项： `mcp`， `requests`， `python-dotenv` （参见 `pyproject.toml`）。
### 仓库布局
```
install.py 跨平台安装程序（venv + 依赖项 + .env + 配置片段）
pyproject.toml 包元数据（入口点：comfyui-flux2-mcp = server:main）
.env.example 文档配置模板 — 复制到.env
src/
server.py MCP服务器 + 两个工具
comfy_client.py ComfyUI HTTP API客户端
config.py 环境驱动配置
templates/ t2i.json，edit.json（API格式工作流）
tests/
test_smoke.py 端到端烟雾测试（调用两个工具针对实时ComfyUI）
```
## 要求
您需要一个可用的ComfyUI安装，并使用FLUX.2 Klein 9B：
- **ComfyUI** 在本地运行（可移植的Windows构建效果很好）
- **FLUX.2 Klein 9B GGUF** — `ComfyUI/models/unet/`中的量化模型文件 ([unsloth/FLUX.2-klein-9B-GGUF](https://huggingface.co/unsloth/FLUX.2-klein-9B-GGUF); 默认预期文件名 `flux-2-klein-9b-Q4_K_S.gguf`）
- **Qwen3 8B 文本编码器** — `ComfyUI/models/text_encoders/`中的 `qwen_3_8b_fp8mixed.safetensors`
- **FLUX.2 VAE** — `ComfyUI/models/vae/`中的 `flux2-vae.safetensors`
- **ComfyUI-GGUF** 自定义节点，由 city96 提供 ([github.com/city96/ComfyUI-GGUF](https://github.com/city96/ComfyUI-GGUF))
- **Python 3.10+** 在您的PATH上
测试环境：ComfyUI v0.21.x，PyTorch 2.11 + CUDA 13，RTX 3060 Laptop 6 GB。大约 **60 秒** 每1024×1024生成， **90 秒** 每编辑一次。Q4量化在6 GB VRAM中舒适地拟合，ComfyUI的低VRAM交换。
## 安装
```bash
git clone https://github.com/kanishka089/comfyui-flux2-mcp.git
cd comfyui-flux2-mcp
python install.py
```
`install.py` 将：
1. 创建一个 `.venv/` 并将软件包 + 依赖项安装到其中
2. 复制 `.env.example` → `.env` （如果丢失）
3. 探测 ComfyUI 是否可在 `http://127.0.0.1:8188` 访问
4. 打印确切的代码片段以粘贴到您的Claude MCP配置中
然后 **编辑 `.env`** 以将 `COMFYUI_INPUT_DIR` 和 `COMFYUI_OUTPUT_DIR` 指向您自己的ComfyUI的 `input/` 和 `output/` 文件夹。
## 在Claude Code中注册
最简单的方法：一条CLI命令（使用 `--scope user` 使工具在**每个**项目中可用，而不仅仅是当前项目）：
```bash
claude mcp add --scope user comfyui-flux2 -- <repo>/.venv/Scripts/python.exe <repo>/src/server.py
```
（在Linux/macOS上，venv Python位于 `<repo>/.venv/bin/python`。）
或手动将其添加到您的MCP配置中（`~/.claude.json`下的 `mcpServers`，或根据您的Claude Code版本为 `~/.claude/mcp.json`）：
```json
"comfyui-flux2": {
"command": "D:/path/to/comfyui-flux2-mcp/.venv/Scripts/python.exe",
"args": ["D:/path/to/comfyui-flux2-mcp/src/server.py"]
}
```
重启Claude Code并运行 `/mcp` — 您应该看到 `comfyui-flux2 ✓ Connected`。
## 用法
在任何Claude对话中：
> *"使用comfyui-flux2生成斯里兰卡茶园日出时的图像"*
> *"使用comfyui-flux2编辑 `D:/photos/garden.png` — 让它成为冬季雪景"*
Claude 调用该工具，等待生成并报告保存的路径（在 `COMFYUI_OUTPUT_DIR/mcp/` 下）。在任何图像查看器中打开文件。
## 配置（`.env`）
| 变量 | 默认值 | 功能 |
|---|---|---|
| `COMFYUI_URL` | `http://127.0.0.1:8188` | ComfyUI监听的位置 |
| `COMFYUI_INPUT_DIR` | （必填） | ComfyUI的 `input/` 文件夹 — MCP服务器必须可写（用于分阶段 `edit_image` 源） |
| `COMFYUI_OUTPUT_DIR` | （必填） | ComfyUI保存输出的位置 |
| `COMFYUI_TIMEOUT` | `300` | 生成超时前的秒数 |
| `FLUX2_MODEL_FILE` | `flux-2-klein-9b-Q4_K_S.gguf` | GGUF unet的文件名 |
| `FLUX2_CLIP_FILE` | `qwen_3_8b_fp8mixed.safetensors` | 文本编码器文件名 |
| `FLUX2_VAE_FILE` | `flux2-vae.safetensors` | VAE文件名 |
| `FLUX2_STEPS` | `4` | 采样步骤（Klein是4步蒸馏） |
如果您切换到不同的FLUX.2变体（不同的量化，4B模型等），只需更改 `FLUX2_MODEL_FILE` — 不需要代码编辑。
`.env` 被git忽略。 将机器特定的路径（和任何秘密，如果您添加一些）排除在版本控制之外。
## 测试
ComfyUI运行时，烟雾测试端到端练习两个工具（生成，然后编辑生成的图像）：
```bash
.venv/Scripts/python.exe tests/test_smoke.py
```
## 故障排除
**`ComfyUI not reachable at http://127.0.0.1:8188`** — ComfyUI未运行。首先启动它（`run_nvidia_gpu.bat` 或您的自定义启动器），等待“Starting server”，然后再次尝试。
**`Workflow validation failed: <node>: Value not in list`** — `FLUX2_MODEL_FILE` / `FLUX2_CLIP_FILE` / `FLUX2_VAE_FILE` 之一与您的 `ComfyUI/models/*/` 文件夹中的文件不匹配。检查拼写并确保文件实际存在。
**工具在300秒后超时** — 启动ComfyUI后的第一个生成操作很慢（模型加载 + 低VRAM交换）。增加 `COMFYUI_TIMEOUT=600` 并尝试一次；后续调用应该很快。
**编辑生成无关图像** — `edit_image` 需要 `source_path` 指向实际图像文件（PNG/JPG）。它在每次调用时将文件复制到ComfyUI的 `input/` 文件夹中；如果复制失败（权限被拒绝，路径错误），工作流将回退到默认值，输出将不反映您的源。
**服务器启动但警告缺少目录** — `server.py` 在启动时积极验证 `COMFYUI_INPUT_DIR` / `COMFYUI_OUTPUT_DIR` 并在stderr上打印警告，如果两者都不存在。修复 `.env` 中的路径。
## 许可证
MCP服务器代码： **MIT** （参见 [LICENSE](LICENSE)）。
FLUX.2 Klein 9B模型本身： **FLUX 非商业许可证** 由Black Forest Labs — **您不能合法出售** 使用FLUX.2 Klein生成的输出。对于商业使用，您需要商业FLUX许可证，或切换底层模型为类似FLUX.1 [schnell]（Apache 2.0）— 相同的workflow大多可以继续使用， `FLUX2_MODEL_FILE` 更改，一个节点类型交换。
## 状态
- **v0.1.0** — 初始发布，两个工具端到端工作。
- 在Windows 11上测试（ComfyUI可移植）。应该在Linux和macOS上工作 — 路径使用 `pathlib.Path` 和正斜杠贯穿始终 — 但这些平台尚未经过测试。 [提交问题](https://github.com/kanishka089/comfyui-flux2-mcp/issues) 如果某些问题出现。
- 范围：此存储库 **仅限图像** 。用于视频（Wan 2.1）和音乐（ACE-Step）的姊妹本地生成MCP服务器作为单独项目存在，不属于此代码库。
