内容
# ComfyMCP
赋予 Claude 通过 ComfyUI 生成图像的能力。只需用自然语言提出您的需求。
```
您： "生成一幅机器人在日落时分作画的图像"
Claude: 我将为您创建该图像。
[构建 7 节点工作流，执行它]
完成！在 2.3 秒内生成了 robot_painting_00001.png。
```
## 您可以使用
安装完成后，Claude 可以处理以下请求：
**图像生成**
- "生成一张猫宇航员在太空中漂浮的图像"
- "使用 SDXL 创建一个 1024x1024 的幻想风景"
- "使用否定提示 '模糊，低质量' 创建肖像"
**模型和系统信息**
- "我有哪些检查点模型？"
- "显示可用的采样器"
- "我的 GPU 内存使用情况是多少？"
**工作流控制**
- "使用 30 步代替 20 步以获得更好的质量"
- "生成 4 个具有不同种子的变体"
- "我的上一次生成的状态是什么？"
Claude 处理所有复杂性 — 发现节点，建立连接，验证工作流和监控执行。
## 工作原理
当您要求 Claude 生成图像时，它会构建一个完整 ComfyUI 工作流：
```
[1] CheckpointLoaderSimple ─────────────────────────────┐
├── MODEL ──────────────────────────────────────────┤
├── CLIP ───┬──→ [3] CLIPTextEncode (positive) ────┤
│ └──→ [4] CLIPTextEncode (negative) ────┤
└── VAE ────────────────────────────────────────────┤
▼
[2] EmptyLatentImage ──────────────────────────→ [5] KSampler
│
▼
[6] VAEDecode
│
▼
[7] SaveImage
```
这会自动发生。Claude：
1. 发现可用的节点及其输入/输出
2. 使用正确的连接构建工作流
3. 在执行前验证所有内容
4. 排队作业并监控完成
5. 报告输出文件名
## 安装
### 先决条件
- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) 运行中（默认：`localhost:8188`）
- [uv](https://docs.astral.sh/uv/) 包管理器
```bash
# 如有需要，安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### Claude 代码（CLI）
```bash
claude mcp add comfyui \
--transport stdio \
--env COMFYUI_HOST=127.0.0.1 \
--env COMFYUI_PORT=8188 \
-- uvx --from git+https://github.com/hernantech/comfymcp comfymcp
```
### Claude 桌面版
添加到您的配置文件：
- Linux: `~/.config/claude/claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"comfyui": {
"command": "uvx",
"args": ["--from", "git+https://github.com/hernantech/comfymcp", "comfymcp"],
"env": {
"COMFYUI_HOST": "127.0.0.1",
"COMFYUI_PORT": "8188"
}
}
}
}
```
### 验证安装
询问 Claude: *"检查 ComfyUI 是否已连接"*
您应该会看到服务器在线且包含 GPU 信息的确认。
## 配置
| 环境变量 | 描述 | 默认值 |
|---------------------|-------------|---------|
| `COMFYUI_HOST` | ComfyUI 服务器地址 | 127.0.0.1 |
| `COMFYUI_PORT` | ComfyUI 服务器端口 | 8188 |
| `COMFYUI_API_KEY` | API 密钥（如果需要） | 无 |
对于远程 ComfyUI 服务器，请更新主机：
```bash
claude mcp add comfyui \
--env COMFYUI_HOST=192.168.1.100 \
...
```
---
## 参考
### 可用的 MCP 工具
<details>
<summary><strong>工作流执行</strong></summary>
| 工具 | 描述 |
|------|-------------|
| `queue_prompt` | 提交工作流以执行 |
| `get_queue_status` | 检查正在运行/待处理的作业 |
| `get_job_status` | 获取特定作业的状态 |
| `get_history` | 查看执行历史 |
| `interrupt_execution` | 停止当前生成 |
| `clear_queue` | 清除待处理作业 |
</details>
<details>
<summary><strong>工作流构建</strong></summary>
| 工具 | 描述 |
|------|-------------|
| `create_workflow` | 开始新的工作流会话 |
| `add_node` | 添加具有输入的节点 |
| `build_workflow` | 完成并验证 |
| `validate_workflow` | 检查错误 |
| `list_nodes` | 搜索可用节点 |
| `get_node_info` | 获取节点规格 |
| `refresh_nodes` | 重新加载节点定义 |
</details>
<details>
<summary><strong>资产和模型</strong></summary>
| 工具 | 描述 |
|------|-------------|
| `list_models` | 列出检查点、LoRAs、VAEs 等 |
| `list_embeddings` | 列出文本反转 |
| `list_output_images` | 列出生成的图像 |
| `get_image` | 检索图像 |
| `upload_image` | 上传用于 img2img |
</details>
<details>
<summary><strong>系统</strong></summary>
| 工具 | 描述 |
|------|-------------|
| `check_connection` | 验证 ComfyUI 是否可达 |
| `get_system_stats` | GPU 内存、系统信息 |
| `free_memory` | 卸载模型、清除缓存 |
| `get_extensions` | 列出已安装的扩展 |
</details>
### MCP 资源
| URI | 描述 |
|-----|-------------|
| `comfyui://nodes` | 所有可用节点 |
| `comfyui://nodes/categories` | 节点类别 |
| `comfyui://nodes/{class_type}` | 特定节点定义 |
| `comfyui://outputs` | 最近的输出 |
| `comfyui://images/{filename}` | 检索图像 |
---
## Python API
用于 MCP 之外的程序化使用：
```python
from comfymcp.workflow import WorkflowBuilder
builder = WorkflowBuilder()
# 节点返回具有命名输出的引用
checkpoint = builder.add_node("CheckpointLoaderSimple",
ckpt_name="sd_turbo.safetensors")
latent = builder.add_node("EmptyLatentImage",
width=512, height=512, batch_size=1)
positive = builder.add_node("CLIPTextEncode",
clip=checkpoint.CLIP, # 命名输出连接
text="美丽的日落")
negative = builder.add_node("CLIPTextEncode",
clip=checkpoint.CLIP,
text="丑陋的，模糊的")
sampler = builder.add_node("KSampler",
model=checkpoint.MODEL,
positive=positive.CONDITIONING,
negative=negative.CONDITIONING,
latent_image=latent.LATENT,
seed=42, steps=4, cfg=1.0,
sampler_name="euler", scheduler="normal", denoise=1.0)
decode = builder.add_node("VAEDecode",
samples=sampler.LATENT,
vae=checkpoint.VAE)
builder.add_node("SaveImage",
images=decode.IMAGE,
filename_prefix="output")
workflow = builder.build()
```
### 模板
```python
from comfymcp.templates import Text2ImgTemplate, Img2ImgTemplate
# 文本到图像
txt2img = Text2ImgTemplate(
checkpoint="sd_turbo.safetensors",
positive_prompt="雄伟的山脉",
negative_prompt="丑陋的，模糊的",
width=512, height=512,
steps=4, cfg=1.0
)
workflow = txt2img.build()
# 图像到图像
img2img = Img2ImgTemplate(
checkpoint="sd_turbo.safetensors",
image="input.png",
positive_prompt="增强细节",
denoise=0.6
)
workflow = img2img.build()
```
### 直接客户端使用
```python
from comfymcp.client import ComfyUIClient
async with ComfyUIClient(host="127.0.0.1", port=8188) as client:
# 排队工作流
result = await client.queue_prompt(workflow)
# 检查状态
history = await client.get_history(prompt_id=result.prompt_id)
# 列出模型
checkpoints = await client.get_models("checkpoints")
```
---
## 要求
- Python 3.10+
- ComfyUI 服务器运行中
- MCP 兼容客户端（Claude Code、Claude Desktop、Cursor 等）
## 许可证
MIT 许可证 - 请参阅 [LICENSE](LICENSE) 获取详细信息。
