ATH-MaaS/Pixelle-MCP · 上手攻略

• 仓库：ATH-MaaS/Pixelle-MCP
• 链接：https://github.com/ATH-MaaS/Pixelle-MCP
• 分类：multimodal · ai-image-generation · MCP
• 作者：Tom
• 更新：2026-08-16

这是什么

Pixelle-MCP 是一个基于 MCP 协议的开源多模态 AIGC 解决方案，核心思路是把 ComfyUI 工作流一键转成 MCP 工具，让 LLM（Claude Desktop、Cursor 等）通过自然语言直接驱动 ComfyUI 图像生成。它支持本地 ComfyUI 和云端 RunningHub 两种执行引擎，提供 Web 界面、MCP 服务器和文件服务的一体化部署。

解决什么问题：ComfyUI 工作流强大但需要手动操作，用户无法用自然语言描述来驱动图像生成 pipeline。Pixelle-MCP 通过把 ComfyUI 的节点图封装成 MCP 工具，让 AI 模型直接读懂"给我生成一张模糊图片"这类指令并自动执行对应工作流。

快速安装

方式一：uvx 一行启动（零配置，推荐体验）

uvx pixelle@latest

⚠️ 需要先安装 uv 环境：curl -LsSf https://astral.sh/uv/install.sh | sh

方式二：pip 安装

pip install -U pixelle
pixelle

方式三：源码 + uv run

git clone https://github.com/AIDC-AI/Pixelle-MCP.git
cd Pixelle-MCP
uv run pixelle

方式四：Docker 生产部署

git clone https://github.com/AIDC-AI/Pixelle-MCP.git
cd Pixelle-MCP
cp .env.example .env
# 编辑 .env 配置 ComfyUI 地址和 LLM 设置
docker compose up -d
docker compose logs -f

首次启动会自动进入配置向导，引导选择执行引擎（本地 ComfyUI 或 RunningHub）和 LLM 提供方。

核心用法

访问地址

启动后访问： - Web 界面：http://localhost:9004（默认账号密码均为 dev） - MCP 端点：http://localhost:9004/pixelle/mcp

端口配置

PORT=8888 pixelle   # 自定义端口

把 ComfyUI 工作流转成 MCP 工具

步骤 1：在 ComfyUI 画布上构建工作流（例如图片高斯模糊），导出为 API 格式文件，命名为 i_blur.json。

⚠️ 必须用 API 格式导出，不能用 UI 格式。预导出文件可从仓库 docs 目录获取：/ATH-MaaS/Pixelle-MCP/blob/main/docs/i_blur.json

步骤 2：在 ComfyUI 中编辑 LoadImage 节点的标题（双击标题），改为 $image.image! 作为参数标记。

步骤 3：把导出的 API 格式 JSON 文件粘贴到 Pixelle Web 界面，让 LLM 自动注册为 MCP 工具。

步骤 4：刷新页面后，直接用自然语言发送图片处理指令，例如"把这张图片做高斯模糊"。

RunningHub 云端模式

只需输入对应的 Workflow ID，无需下载上传工作流文件。

ComfyUI 工作流节点标题 DSL 语法

在 ComfyUI 画布中双击节点标题，使用以下语法定义参数和输出：

$param_name.field_name[!][:<description>]

• $param_name：生成的 MCP 工具函数参数名
• field_name：对应节点的输入字段名
• !：标记为必填参数
• ~：URL 上传处理（系统自动下载 URL 并上传到 ComfyUI）
• : 后跟参数描述

示例：

类型推断：系统根据节点字段的当前值自动推断类型（int / float / bool / str）。

MCP 描述节点：在节点标题写 MCP，在 String (Multiline) 节点的 value 字段写详细工具描述。

MCP 客户端接入

在 Claude Desktop 或 Cursor 的 MCP 配置中添加：

{
  "mcpServers": {
    "pixelle": {
      "command": "uvx",
      "args": ["--from", "pixelle", "pixelle-mcp"]
    }
  }
}

或 pip 安装后直接：

{
  "mcpServers": {
    "pixelle": {
      "command": "pixelle-mcp"
    }
  }
}

⚠️ MCP 连接地址为 http://localhost:9004/pixelle/mcp，Pixelle 服务必须先启动。

本地 ComfyUI vs RunningHub 对比

典型适用场景

1. AI 图像生成流水线自动化：用自然语言驱动 ComfyUI 工作流，无需手动在画布上操作节点。
2. 多工具组合：把多个 ComfyUI 工作流注册为不同 MCP 工具，LLM 按需调用组合。
3. 无 GPU 用户：RunningHub 模式让没有高性能 GPU 的用户也能用 ComfyUI 生态。
4. AI 应用集成：通过 MCP 把 ComfyUI 能力嵌入 Claude Desktop、Cursor 等 AI IDE。
5. 批量图像处理：LLM 自动调度多个工作流执行图片处理任务。

坑与注意

1. 工作流必须是 API 格式：导出时必须选 API format，UI format 不可用，否则注册失败。
2. 节点标题必须按 DSL 语法编辑：没有正确设置参数标记的节点不会被注册为 MCP 工具。
3. 本地 ComfyUI 需预先测试工作流：文档明确建议"先在 ComfyUI 中测试工作流确保能正常运行"，否则 Pixelle 执行会失败。
4. RunningHub 需要 API Key：云端模式需注册 RunningHub 并获取 API Key。
5. 端口 9004 占用：若端口被占用，需通过 PORT 环境变量修改。
6. Web 默认密码为 dev：生产部署务必修改默认密码。
7. ComfyUI 自定义节点：若工作流使用了本地 ComfyUI 实例上没有安装的自定义节点，本地模式会失败。
8. LLM 配置：Pixelle 需要至少配置一个 LLM 提供方（OpenAI / Ollama 等），首次启动向导引导配置。

与同类对比

Pixelle-MCP 的核心差异化：唯一把"自然语言驱动 ComfyUI"做成零代码注册 MCP 工具的产品，RunningHub 模式解决了无 GPU 用户的门槛问题。

一句话推荐结论

Pixelle-MCP 是目前将 ComfyUI 工作流接入 LLM Agent 工作流最低门槛的方案，适合想用自然语言驱动图像生成、或将 ComfyUI 能力嵌入 AI IDE 的开发者。

最小可跑命令

# 前置：uv 环境，Python 3.11（推荐）
# 方式一：零配置体验
uvx pixelle@latest

# 方式二：pip 安装
pip install -U pixelle
pixelle

# 启动后访问
# Web: http://localhost:9004  (账号密码: dev / dev)
# MCP: http://localhost:9004/pixelle/mcp

# Docker 方式（需 Docker + docker compose）
# git clone 后编辑 .env 再启动
docker compose up -d

⚠️ Python 版本：README 未明确标注最低 Python 版本，文档提到"Python 3.11 environment"，建议使用 Python 3.11+；uv run 方式依赖 pyproject.toml 中声明的依赖。

来源

• https://github.com/ATH-MaaS/Pixelle-MCP（README + 6 篇文档）
• https://github.com/AIDC-AI/Pixelle-MCP（star-history 指向的实际上游仓库）
• https://pixelle.ai（官方站点）