技术文档摘要

<h1 align="center">🎨 Pixelle MCP - 全模态代理框架</h1> <p align="center"><b>English</b> | <a href="README_CN.md">中文</a></p> <p align="center">✨ 基于MCP协议的AIGC解决方案，支持本地ComfyUI和云ComfyUI（RunningHub）模式，无需代码即可无缝转换工作流为MCP工具。</p>

https://github.com/user-attachments/assets/65422cef-96f9-44fe-a82b-6a124674c417

📋 最近更新

• ✅ 2025-09-29: 添加了对RunningHub云ComfyUI的支持，无需本地GPU和ComfyUI环境即可执行工作流
• ✅ 2025-09-03: 架构重构，从三个服务统一到一个应用；添加了CLI工具支持；发布至PyPI
• ✅ 2025-08-12: 集成了LiteLLM框架，增加了对Gemini、DeepSeek、Claude、Qwen等多模型的支持

🚀 功能

• ✅ 🔄 全模态支持：支持TISV（文本、图像、声音/语音、视频）全模态转换和生成
• ✅ 🚀 双执行模式：本地ComfyUI自托管环境 + RunningHub云ComfyUI服务，用户可根据需求灵活选择
• ✅ 🧩 ComfyUI生态系统：基于ComfyUI，继承开放的ComfyUI生态系统的所有能力
• ✅ 🔧 零代码开发：定义并实现工作流作为MCP工具的解决方案，支持零代码开发和动态添加新的MCP工具
• ✅ 🗄️ MCP服务器：基于MCP协议，支持与任何MCP客户端（包括但不限于Cursor、Claude Desktop等）集成
• ✅ 🌐 Web界面：基于Chainlit框架开发，继承Chainlit的UI控件，并支持与其他MCP服务器集成
• ✅ 📦 一键部署：支持PyPI安装、CLI命令、Docker等多种部署方式，开箱即用
• ✅ ⚙️ 简化配置：采用环境变量配置方案，简单直观的配置
• ✅ 🤖 多LLM支持：支持多个主流LLM，包括OpenAI、Ollama、Gemini、DeepSeek、Claude、Qwen等

📁 项目架构

Pixelle MCP采用了统一架构设计，将MCP服务器、Web界面和文件服务整合到一个应用中，提供：

• 🌐 Web界面：基于Chainlit的聊天界面，支持多模态交互
• 🔌 MCP端点：供外部MCP客户端（如Cursor、Claude Desktop）连接
• 📁 文件服务：处理文件上传、下载和存储
• 🛠️ 工作流引擎：支持本地ComfyUI和云ComfyUI（RunningHub）工作流，自动将工作流转换为MCP工具

<div id="tutorial-start" />

🏃‍♂️ 快速开始

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

🎯 方法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
  供MCP客户端如Cursor、Claude Desktop连接

💡 端口配置：默认端口为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!:Input image URL
• 意义：创建一个名为image的必需参数，映射到节点的image字段

URL上传处理示例：

• 设置任意节点标题为：$image.~image!:Input 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. 在值字段中输入详细的工具描述

⚠️ 重要注意事项

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

<div id="tutorial-end" />

💬 社区

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

Discord社区	微信群
<img src="docs/discord.png" alt="Discord社区" width="250" />	<img src="docs/wechat.png" alt="微信群" width="250" />

🤝 如何贡献

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

🐛 报告问题

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

💡 功能建议

• 🚀 在Issues提交功能请求
• 💭 描述您想要的功能及其应用场景
• 🎯 解释如何改进用户体验

🔧 代码贡献

📋 贡献流程

1. 🍴 分叉此仓库到您的GitHub账户
2. 🌿 创建特性分支：git checkout -b feature/your-feature-name
3. 💻 开发并添加相应测试
4. 📝 提交更改：git commit -m "feat: 添加您的功能"
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）。