Pixelle MCP

🚀 🎨 Pixelle MCP - 全模态智能体框架

Pixelle MCP 是基于 MCP 协议的 AIGC 解决方案，能零代码将 ComfyUI 工作流转换为 MCP 工具，实现 LLM 与 ComfyUI 的无缝集成，为多模态内容生成提供强大支持。

📁 项目结构

• mcp-base：🔧 基础服务，提供文件存储和共享服务能力。
• mcp-client：🌐 MCP 客户端，基于 Chainlit 构建的 Web 界面。
• mcp-server：🗄️ MCP 服务器，提供各种 AIGC 工具和服务。

项目结构

✨ 主要特性

• ✅ 🔄 全模态支持：支持 TISV（文本、图像、声音/语音、视频）全模态转换和生成。
• ✅ 🧩 ComfyUI 生态系统：服务器端基于 ComfyUI 构建，继承了开放的 ComfyUI 生态系统的所有能力。
• ✅ 🔧 零代码开发：定义并实现了“工作流即 MCP 工具”的解决方案，支持零代码开发和动态添加新的 MCP 工具。
• ✅ 🗄️ MCP 服务器：服务器基于 MCP 协议提供功能，支持与任何 MCP 客户端集成（包括但不限于 Cursor、Claude Desktop 等）。
• ✅ 🌐 MCP 客户端：客户端基于 Chainlit 框架开发，继承了 Chainlit 的 UI 控件，支持与更多 MCP 服务器集成。
• ✅ 🔄 灵活部署：支持仅将服务器端作为 MCP 服务器独立部署，或仅将客户端作为 MCP 客户端独立部署，或两者组合部署。
• ✅ ⚙️ 统一配置：使用 YAML 配置方案，一个配置文件管理所有服务。

🚀 快速开始

📥 1. 克隆源代码并配置服务

📦 1.1 克隆源代码

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

⚙️ 1.2 配置服务

项目使用统一的 YAML 配置方案：

# 复制配置示例文件
cp config.yml.example config.yml
# 根据需要编辑配置项

📋 详细配置说明： 配置文件包含三个主要部分：基础服务、MCP 服务器和 MCP 客户端。每个部分在 中都有详细的配置项描述。 🔍 配置检查清单：

• ✅ 将 config.yml.example 复制到 config.yml。
• ✅ 配置 ComfyUI 服务地址（确保 ComfyUI 正在运行）。
• ✅ 配置至少一个 LLM 模型（OpenAI 或 Ollama）。
• ✅ 端口号未被其他服务占用（9001、9002、9003）。

🔧 2. 添加 MCP 工具（可选）

此步骤可选，仅影响您的智能体能力。如果目前不需要，可以跳过。 mcp-server/workflows 目录默认包含一组流行的工作流。运行以下命令将它们复制到您的 mcp-server。服务启动时，它们将自动转换为 MCP 工具供 LLM 使用。 注意：强烈建议在复制之前在您的 ComfyUI 画布中测试工作流，以确保后续执行顺利。

cp -r mcp-server/workflows/* mcp-server/data/custom_workflows/

🚀 3. 启动服务

🎯 3.1 使用 Docker 启动（推荐）

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

🛠️ 3.2 一键脚本启动

需要 uv 环境。 Linux/macOS 用户：

# 启动所有服务（前台）
./run.sh

# 或者

# 启动所有服务（后台）
./run.sh start --daemon

Windows 用户： 只需双击根目录中的 run.bat 脚本。

🛠️ 3.3 手动启动服务

需要 uv 环境。 启动基础服务（mcp-base）：

cd mcp-base
# 安装依赖（仅首次运行或更新后需要）
uv sync
# 启动服务
uv run main.py

启动服务器（mcp-server）：

cd mcp-server
# 安装依赖（仅首次运行或更新后需要）
uv sync
# 启动服务
uv run main.py

启动客户端（mcp-client）：

cd mcp-client
# 安装依赖（仅首次运行或更新后需要）
uv sync
# 启动服务（开发模式下热重载：uv run chainlit run main.py -w --port 9003）
uv run main.py

🌐 4. 访问服务

启动后，服务地址如下：

• 客户端：🌐 http://localhost:9003（Chainlit Web UI，默认用户名和密码均为 dev，可在 中更改）
• 服务器：🗄️ http://localhost:9002/sse（MCP 服务器）
• 基础服务：🔧 http://localhost:9001/docs（文件存储和基础 API）

🛠️ 添加您自己的 MCP 工具

⚡ 一个工作流 = 一个 MCP 工具

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

• 📝 在 ComfyUI 中构建一个用于图像高斯模糊的工作流（在此获取），然后将 LoadImage 节点的标题设置为 $image.image!，如下所示：
• 📤 将其导出为 API 格式文件并重命名为 i_blur.json。您可以自己导出，也可以使用我们预先导出的版本（在此获取）
• 📋 复制导出的 API 工作流文件（必须是 API 格式），在网页上输入，让 LLM 添加此工具。
• ✨ 发送后，LLM 将自动将此工作流转换为 MCP 工具。
• 🎨 现在，刷新页面并发送任何图像，即可通过 LLM 进行高斯模糊处理。

🔌 2. 添加复杂的 MCP 工具

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

🔧 ComfyUI 工作流自定义规范

🎨 工作流格式

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

📝 参数定义规范

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

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

🔍 语法解释：

• param_name：生成的 MCP 工具函数的参数名称。
• field_name：节点中对应的输入字段。
• !：表示此参数为必需参数。
• description：参数描述。

💡 示例：

必需参数示例：

• 将 LoadImage 节点标题设置为：$image.image!:输入图像 URL
• 含义：创建一个名为 image 的必需参数，映射到节点的 image 字段。 可选参数示例：
• 将 EmptyLatentImage 节点标题设置为：$width.width:图像宽度，默认 512
• 含义：创建一个名为 width 的可选参数，映射到节点的 width 字段，默认值为 512。

🎯 类型推断规则

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

• 🔢 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 格式。

💬 社区

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

🤝 如何贡献

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

🐛 报告问题

• 📋 在 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

📄 许可证

本项目根据 MIT 许可证发布（LICENSE，SPDX 许可证标识符：MIT）。