AI导哈

全模态代理框架

基于MCP协议的全模态代理框架，支持本地ComfyUI和云端ComfyUI模式，零代码将工作流转换为MCP工具。

  • by ATH-MaaS
  • Python
  • 本地部署
  • 1131 星标
  • 更新于
在 GitHub 查看 AIDC-AI/Pixelle-MCP

使用说明

🎨 Pixelle MCP - Omnimodal Agent Framework

English | 中文

✨ An AIGC solution based on the MCP protocol, supporting both local ComfyUI and cloud ComfyUI (RunningHub) modes, seamlessly converting workflows into MCP tools with zero code.

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生态系统：基于 Comfy用户界面，继承了开放式ComfyUI生态系统的所有功能
  • ✅ 🔧 零代码开发：定义并实施工作流作为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工具

🏃‍♂️ 快速开始

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

🎯 方法一：一键体验

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

🚀 临时运行

# First you need to install the uv environment
# Start with one command, no system installation required
uvx pixelle@latest

📚 查看uvx CLI参考→

📦 持续安装

# Here you need to install it in the python3.11 environment
# Install to system
pip install -U pixelle

# Start service
pixelle

📚 查看pip CLI参考→

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

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

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

📥 1.获取源代码

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

🚀 2.启动服务

# Interactive mode (recommended)
uv run pixelle

📚 查看完整的CLI参考→

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

# Copy example workflows to data directory (run this in your desired project directory)
cp -r workflows/* ./data/custom_workflows/

⚠️ 重要：请确保首先在ComfyUI中测试工作流，以确保它们正常运行，否则执行将失败。

🐳 方法3：Docker部署

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

📋 1.准备配置

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

# Create environment configuration file
cp .env.example .env
# Edit .env file to configure your ComfyUI address and LLM settings

🚀 2.启动容器

# Start all services in background
docker compose up -d

# View logs
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!: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. 添加a String (Multiline) 或类似的文本节点（必须具有单个字符串属性，节点字段应为：value、text、string之一）
  2. 将节点标题设置为： MCP
  3. 在值字段中输入详细的工具描述

⚠️ 重要说明

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

💬 社区

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

Discord社区 微信群

🤝 如何做出贡献

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

🐛 报告问题

  • 📋 提交错误报告 问题 页
  • 🔍 请在提交前搜索类似问题
  • 📝 详细描述复制步骤和环境

💡 功能建议

  • 🚀 在中提交功能请求 问题
  • 💭 描述您想要的功能及其用例
  • 🎯 解释它如何改善用户体验

🔧 代码贡献

📋 贡献过程

  1. 🍴 将此仓库分叉到您的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请求

🎨 代码的风格

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

🧩 贡献工作流

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

🙏 致谢

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

许可证

该项目在MIT许可证下发布(许可证SPDX 许可证标识符：MIT）。

⭐ 明星历史

相关 MCP