内容
<h1 align="center">🎨 Pixelle MCP - 全模态智能代理框架</h1>
<p align="center"><b>简体中文</b> | <a href="README.md">English</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](https://pypi.org/project/pixelle/)
- ✅ **2025-08-12**: 集成LiteLLM框架，新增Gemini、DeepSeek、Claude、Qwen等多模型支持
## 🚀 功能特点
- ✅ 🔄 **全模态支持**: 支持TISV（文本、图像、声音/语音、视频）全模态转换与生成
- ✅ 🚀 **双重执行模式**: 本地ComfyUI自托管环境 + RunningHub云端ComfyUI服务，用户可根据需求灵活选择
- ✅ 🧩 **ComfyUI生态**: 基于 [ComfyUI](https://github.com/comfyanonymous/ComfyUI)，继承开源ComfyUI生态的所有能力
- ✅ 🔧 **零代码开发**: 定义并实现工作流即MCP工具解决方案，实现零代码开发和动态新增MCP工具
- ✅ 🗄️ **MCP服务端**: 基于 [MCP](https://modelcontextprotocol.io/introduction) 协议，支持与任何MCP客户端（包括但不限于Cursor、Claude Desktop等）集成
- ✅ 🌐 **网页界面**: 基于 [Chainlit](https://github.com/Chainlit/chainlit) 框架开发，继承Chainlit的UI控件，支持与更多MCP服务端集成
- ✅ 📦 **一键部署**: 支持PyPI安装、CLI命令、Docker等部署方式，开箱即用
- ✅ ⚙️ **简化配置**: 采用环境变量配置方案，配置简单直观
- ✅ 🤖 **多LLM支持**: 支持多个主流LLM，包括OpenAI、Ollama、Gemini、DeepSeek、Claude、Qwen等
## 📁 项目架构
Pixelle MCP采用 **统一架构设计**，将MCP服务端、网页界面和文件服务集成于一体，提供：
- 🌐 **网页界面**: 基于Chainlit的聊天界面，支持多模态交互
- 🔌 **MCP端点**: 供外部MCP客户端（如Cursor、Claude Desktop）连接
- 📁 **文件服务**: 处理文件上传、下载和存储
- 🛠️ **工作流引擎**: 支持本地ComfyUI和云端ComfyUI（RunningHub）工作流，自动转换工作流为MCP工具
<div id="tutorial-start" />
## 🏃♂️ 快速开始
选择最适合您的部署方式，从简单到复杂：
### 🎯 方法1：快速体验
> 💡 **零配置启动，适合快速体验和测试**
#### 🚀 临时运行
```bash
# 首先需要安装uv环境
# 一键启动，无需系统安装
uvx pixelle@latest
```
📚 **[查看uvx CLI参考 →](docs/CLI.md#uvx-method)**
#### 📦 持久化安装
```bash
# 这里需要在python3.11环境中安装
# 安装到系统
pip install -U pixelle
# 启动服务
pixelle
```
📚 **[查看pip CLI参考 →](docs/CLI.md#pip-install-method)**
启动后，系统将自动进入 **配置向导**，引导您完成执行引擎选择（ComfyUI/RunningHub）和LLM配置。
### 🛠️ 方法2：本地开发部署
> 💡 **支持自定义工作流和二次开发**
#### 📥 1. 获取源码
```bash
git clone https://github.com/AIDC-AI/Pixelle-MCP.git
cd Pixelle-MCP
```
#### 🚀 2. 启动服务
```bash
# 交互模式（推荐）
uv run pixelle
```
📚 **[查看完整CLI参考 →](docs/CLI.md#uv-run-method)**
#### 🔧 3. 新增自定义工作流（可选）
```bash
# 将示例工作流复制到数据目录（在您期望的项目目录中运行）
cp -r workflows/* ./data/custom_workflows/
```
**⚠️ 重要提示**：确保在ComfyUI中测试工作流以确保其正常运行，否则执行将失败。
### 🐳 方法3：Docker部署
> 💡 **适用于生产环境和容器化部署**
#### 📋 1. 准备配置
```bash
git clone https://github.com/AIDC-AI/Pixelle-MCP.git
cd Pixelle-MCP
# 创建环境配置文件
cp .env.example .env
# 编辑.env文件，配置您的ComfyUI地址和LLM设置
```
#### 🚀 2. 启动容器
```bash
# 在后台启动所有服务
docker compose up -d
# 查看日志
docker compose logs -f
```
### 🌐 访问服务
无论您使用哪种方法，启动后都可以通过以下方式访问：
- **🌐 网页界面**: 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中构建图像高斯模糊工作流（[获取示例](docs/i_blur_ui.json)），并将`LoadImage`节点的标题设置为 `$image.image!`，如图所示：
* 📤 导出为API格式文件，并重命名为 `i_blur.json`。您可以自己导出或使用我们预先导出的版本（[获取示例](docs/i_blur.json)）
* 📋 将导出的API工作流文件（必须是API格式）输入到网页中，让LLM新增此工具
* ✨ 发送后，LLM将自动将此工作流转换为MCP工具
* 🎨 现在，刷新页面并发送任意图像，通过LLM进行高斯模糊处理
### 🔌 2. 新增复杂MCP工具
步骤与上述相同，只是工作流部分不同（下载工作流：[UI格式](docs/t2i_by_flux_turbo_ui.json) 和 [API格式](docs/t2i_by_flux_turbo.json)）
> **注意：** 使用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. 在值字段中输入详细的工具描述
### ⚠️ 重要注意事项
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](https://github.com/AIDC-AI/Pixelle-MCP/issues) 页面提交错误报告
* 🔍 提交前请搜索类似问题
* 📝 详细描述重现步骤和环境
### 💡 功能建议
* 🚀 在 [Issues](https://github.com/AIDC-AI/Pixelle-MCP/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](https://pep8.org/) 风格指南
* 📖 为新功能添加适当的文档和注释
### 🧩 贡献工作流
* 📦 与社区分享您的ComfyUI工作流
* 🛠️ 提交经过测试的工作流文件
* 📚 添加工作流的使用说明和示例
## 🙏 致谢
❤️ 特别感谢以下组织、项目和团队对本项目的支持和实现。
* 🧩 [ComfyUI](https://github.com/comfyanonymous/ComfyUI)
* 💬 [Chainlit](https://github.com/Chainlit/chainlit)
* 🔌 [MCP](https://modelcontextprotocol.io/introduction)
* 🎬 [WanVideo](https://github.com/Wan-Video/Wan2.1)
* ⚡ [Flux](https://github.com/black-forest-labs/flux)
* 🤖 [LiteLLM](https://github.com/BerriAI/litellm)
## License
本项目在MIT License下发布 ([LICENSE](LICENSE)，SPDX-License-identifier: MIT).
## ⭐ Star历史
[](https://star-history.com/#AIDC-AI/Pixelle-MCP&Date)
