Pixelle Mcp

🏃‍♂️ 快速开始

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

🎯 方式 1：一键体验

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

🚀 临时运行

# 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. 添加一个 String (Multiline) 或类似文本节点（必须仅包含一个字符串属性，且节点字段必须是以下之一：value、text、string）
2. 将节点标题设为：MCP
3. 在 value 字段中输入详细的工具描述

⚠️ 重要注意事项

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