🏃‍♂️ 快速开始

根据您的需求选择合适的部署方式，从简单到复杂：

🎯 方法1：一键体验

💡 零配置启动，非常适合快速体验和测试

🚀 临时运行

# 首先需要安装uv环境
# 一条命令即可启动，无需系统安装
uvx pixelle@latest

📚 查看uvx CLI参考 →

📦 永久安装

# 此处需要在python3.11环境中安装
# 安装到系统
pip install -U pixelle

# 启动服务
pixelle

📚 查看pip CLI参考 →

启动后，系统会自动进入配置向导，引导您完成执行引擎选择（ComfyUI/RunningHub）和LLM配置。

🛠️ 方法2：本地开发部署

💡 支持自定义工作流和二次开发

📥 1. 获取源码

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

🚀 2. 启动服务

# 交互式模式（推荐）
uv run pixelle

📚 查看完整CLI参考 →

🔧 3. 添加自定义工作流（可选）

# 将示例工作流复制到data目录（请在您希望使用的项目目录中执行此操作）
cp -r workflows/* ./data/custom_workflows/

⚠️ 注意: 请务必先在ComfyUI中测试工作流，确保其正常运行，否则执行将会失败。

🐳 方法3：Docker部署

💡 适用于生产环境和容器化部署

📋 1. 准备配置

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

# 创建环境配置文件
cp .env.example .env
# 编辑.env文件以配置您的ComfyUI地址和LLM设置

🚀 2. 启动容器

# 在后台启动所有服务
docker compose up -d

# 查看日志
docker compose logs -f

🌐 访问服务

无论您使用哪种方法，启动后均可通过以下方式访问：

• 🌐 Web界面: http://localhost:9004
  默认用户名和密码均为dev，可在启动后修改
• 🔌 MCP端点: http://localhost:9004/pixelle/mcp
  供Cursor、Claude Desktop等MCP客户端连接

💡 端口配置: 默认端口为9004，可通过环境变量PORT=your_port进行自定义。

⚙️ 初始配置

首次启动时，系统会自动检测配置状态：

1. 🚀 执行引擎选择: 选择本地ComfyUI或RunningHub云服务
2. 🤖 LLM配置: 至少配置一个LLM提供商（OpenAI、Ollama等）
3. 📁 工作流目录: 系统会自动创建必要的目录结构

🌐 RunningHub云模式优势

• ✅ 无硬件要求: 无需本地GPU或其他高性能硬件
• ✅ 无需环境搭建: 无需在本地安装和配置ComfyUI
• ✅ 即开即用: 注册并获取API密钥即可立即开始使用
• ✅ 性能稳定: 专业的云基础设施确保执行稳定
• ✅ 自动扩展: 自动处理并发请求和资源分配

🏠 本地ComfyUI模式优势

• ✅ 完全控制: 完全掌控执行环境和模型版本
• ✅ 隐私保护: 所有数据处理均在本地进行，确保数据隐私
• ✅ 自定义模型: 支持云端未提供的自定义模型和节点
• ✅ 无网络依赖: 可在无互联网连接的情况下离线工作
• ✅ 成本可控: 对于高频使用场景，无需支付云服务费用

🆘 需要帮助？ 加入社区群组获取支持（见下方社区部分）

🛠️ 添加您自己的MCP工具

⚡ 一个工作流 = 一个MCP工具，支持两种添加方式：

📋 方式1：本地ComfyUI工作流 - 导出API格式的工作流文件 📋 方式2：RunningHub工作流ID - 直接使用云端工作流ID

🎯 1. 添加最简单的 MCP 工具

• 📝 在 ComfyUI 中构建一个图像高斯模糊的工作流（点击获取），然后将 LoadImage 节点的标题设置为 $image.image!，如下所示：

• 📤 将其导出为 API 格式的文件，并重命名为 i_blur.json。你可以自行导出，也可以使用我们预导出的版本（点击获取）

• 📋 复制导出的 API 工作流文件（必须是 API 格式），将其输入到网页上，让 LLM 添加这个工具。

  

• ✨ 发送后，LLM 会自动将此工作流转换为 MCP 工具。

  

• 🎨 现在，刷新页面并上传任意图片，即可通过 LLM 进行高斯模糊处理。

  

🔌 2. 添加复杂的 MCP 工具

步骤与上述相同，仅工作流部分有所不同（下载工作流：UI 格式 和 API 格式）

注意：使用 RunningHub 时，只需输入对应的工作流 ID 即可，无需下载和上传工作流文件。

🔧 ComfyUI 工作流自定义规范

🎨 工作流格式

系统支持 ComfyUI 工作流。你只需在画布上设计好工作流，并将其导出为 API 格式。在节点标题中使用特殊语法来定义参数和输出。

📝 参数定义规范

在 ComfyUI 画布中，双击节点标题进行编辑，使用以下 DSL 语法来定义参数：

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

🔍 语法解释：

• param_name：生成的 MCP 工具函数的参数名称
• ~：可选，表示 URL 参数上传处理，返回相对路径
• field_name：节点中的对应输入字段
• !：表示该参数为必填项
• description：参数的描述

💡 示例：

必填参数示例：

• 将 LoadImage 节点标题设置为：$image.image!:输入图像 URL
• 含义：创建一个名为 image 的必填参数，映射到节点的 image 字段

URL 上传处理示例：

• 将任意节点标题设置为：$image.~image!:输入图像 URL
• 含义：创建一个名为 image 的必填参数，系统会自动下载 URL 并上传到 ComfyUI，返回相对路径

📝 注意：LoadImage、VHS_LoadAudioUpload、VHS_LoadVideo 等节点具有内置功能，无需添加 ~ 标记

🎯 类型推断规则

系统会根据节点字段的当前值自动推断参数类型：

• 🔢 int：整数值（例如 512、1024）
• 📊 float：浮点数值（例如 1.5、3.14）
• ✅ bool：布尔值（例如 true、false）
• 📝 str：字符串值（默认类型）

📤 输出定义规范

🤖 方法 1：自动检测输出节点

系统会自动检测以下常见输出节点：

• 🖼️ SaveImage - 图像保存节点
• 🎬 SaveVideo - 视频保存节点
• 🔊 SaveAudio - 音频保存节点
• 📹 VHS_SaveVideo - VHS 视频保存节点
• 🎵 VHS_SaveAudio - VHS 音频保存节点

🎯 方法 2：手动标记输出

通常用于多输出情况 在任何节点标题中使用 $output.var_name 来标记输出：

• 将节点标题设置为：$output.result
• 系统会将该节点的输出作为工具的返回值

📄 工具描述配置（可选）

你可以在工作流中添加一个标题为 MCP 的节点来提供工具描述：

1. 添加一个 String (Multiline) 或类似文本节点（必须具有单个字符串属性，且节点字段应为：value、text 或 string）
2. 将节点标题设置为：MCP
3. 在 value 字段中输入详细的工具描述

⚠️ 重要提示

1. 🔒 参数校验：可选参数（没有 !）必须在节点中设置默认值
2. 🔗 节点连接：已连接到其他节点的字段不会被解析为参数
3. 🏷️ 工具命名：导出文件名将用作工具名称，建议使用有意义的英文名称
4. 📋 详细描述：提供详细的参数描述，以提升用户体验
5. 🎯 导出格式：必须导出为 API 格式，不要导出为 UI 格式

💬 社区

扫描下方二维码加入我们的社区，获取最新动态和技术支持：

Discord 社区	微信群

🤝 如何贡献

我们欢迎任何形式的贡献！无论你是开发者、设计师还是用户，都可以通过以下方式参与项目：

🐛 报告问题

• 📋 在 Issues 页面提交 bug 报告
• 🔍 提交前请先搜索是否有类似问题
• 📝 详细描述复现步骤和环境

💡 功能建议

• 🚀 在 Issues 中提交功能需求
• 💭 描述你想要的功能及其使用场景
• 🎯 解释它如何提升用户体验

🔧 代码贡献

📋 贡献流程

1. 🍴 将本仓库 fork 到你的 GitHub 账号
2. 🌿 创建功能分支：git checkout -b feature/your-feature-name
3. 💻 开发并添加相应的测试
4. 📝 提交更改：git commit -m "feat: add your feature"
5. 📤 推送到你的仓库：git push origin feature/your-feature-name
6. 🔄 向主仓库发起 Pull Request

🎨 代码风格

• 🐍 Python 代码遵循 PEP 8 风格指南
• 📖 为新功能添加适当的文档和注释

🧩 贡献工作流

• 📦 与社区分享你的 ComfyUI 工作流
• 🛠️ 提交经过测试的工作流文件
• 📚 为工作流添加使用说明和示例

🙏 致谢

❤️ 衷心感谢以下组织、项目和团队对本项目开发与实施的支持。

• 🧩 ComfyUI

• 💬 Chainlit

• 🔌 MCP

• 🎬 WanVideo

• ⚡ Flux

• 🤖 LiteLLM

许可证

本项目采用 MIT 许可证发布（LICENSE，SPDX-License-Identifier: MIT）。

⭐ 星标历史

# 确保已安装 uv，然后执行以下命令直接运行
uvx pixelle@latest

# 1. 安装到系统 (确保 python 版本为 3.11)
pip install -U pixelle

# 2. 启动服务
pixelle

# 1. 克隆项目
git clone https://github.com/AIDC-AI/Pixelle-MCP.git
cd Pixelle-MCP

# 2. 使用 uv 运行 (交互式模式)
uv run pixelle

# 1. 准备配置文件
git clone https://github.com/AIDC-AI/Pixelle-MCP.git
cd Pixelle-MCP
cp .env.example .env
# 编辑 .env 文件，配置 ComfyUI 地址和 LLM Key

# 2. 启动容器
docker compose up -d

# 查看日志
docker compose logs -f