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）。