Skip to content
Back to search

Pixelle-MCP

An Open-Source Multimodal AIGC Solution based on ComfyUI + MCP + LLM https://pixelle.ai

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ath-maas--pixelle-mcp/badge.svg)](/listings/ath-maas--pixelle-mcp)

HTML

<a href="/listings/ath-maas--pixelle-mcp"><img src="/api/listings/ath-maas--pixelle-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Choose the deployment method that best suits your needs, from simple to complex:

🎯 Method 1: One-click Experience

> πŸ’‘ **Zero configuration startup, perfect for quick experience and testing**

πŸš€ Temporary Run

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

πŸ“š **[View uvx CLI Reference β†’](docs/CLI.md#uvx-method)**

πŸ“¦ Persistent Installation

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

# Start service
pixelle

πŸ“š **[View pip CLI Reference β†’](docs/CLI.md#pip-install-method)**

After startup, it will automatically enter the **configuration wizard** to guide you through execution engine selection (ComfyUI/RunningHub) and LLM configuration.

πŸ› οΈ Method 2: Local Development Deployment

> πŸ’‘ **Supports custom workflows and secondary development**

πŸ“₯ 1. Get Source Code

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

πŸš€ 2. Start Service

# Interactive mode (recommended)
uv run pixelle

πŸ“š **[View Complete CLI Reference β†’](docs/CLI.md#uv-run-method)**

πŸ”§ 3. Add Custom Workflows (Optional)

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

**⚠️ Important**: Make sure to test workflows in ComfyUI first to ensure they run properly, otherwise execution will fail.

🐳 Method 3: Docker Deployment

> πŸ’‘ **Suitable for production environments and containerized deployment**

πŸ“‹ 1. Prepare Configuration

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 Container

# Start all services in background
docker compose up -d

# View logs
docker compose logs -f

🌐 Access Services

Regardless of which method you use, after startup you can access via:

- **🌐 Web Interface**: http://localhost:9004 *Default username and password are both `dev`, can be modified after startup* - **πŸ”Œ MCP Endpoint**: http://localhost:9004/pixelle/mcp *For MCP clients like Cursor, Claude Desktop to connect*

**πŸ’‘ Port Configuration**: Default port is 9004, can be customized via environment variable `PORT=your_port`.

βš™οΈ Initial Configuration

On first startup, the system will automatically detect configuration status:

1. **πŸš€ Execution Engine Selection**: Choose between local ComfyUI or RunningHub cloud service 2. **πŸ€– LLM Configuration**: Configure at least one LLM provider (OpenAI, Ollama, etc.) 3. **πŸ“ Workflow Directory**: System will automatically create necessary directory structure

🌐 RunningHub Cloud Mode Advantages

- βœ… **Zero Hardware Requirements**: No need for local GPU or high-performance hardware - βœ… **No Environment Setup**: No need to install and configure ComfyUI locally - βœ… **Ready to Use**: Register and get API key to start immediately - βœ… **Stable Performance**: Professional cloud infrastructure ensures stable execution - βœ… **Auto Scaling**: Automatically handles concurrent requests and resource allocation

🏠 Local ComfyUI Mode Advantages

- βœ… **Full Control**: Complete control over execution environment and model versions - βœ… **Privacy Protection**: All data processing happens locally, ensuring data privacy - βœ… **Custom Models**: Support for custom models and nodes not available in cloud - βœ… **No Network Dependency**: Can work offline without internet connection - βœ… **Cost Control**: No cloud service fees for high-frequency usage

**πŸ†˜ Need Help?** Join community groups for support (see Community section below)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 341 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">🎨 Pixelle MCP - Omnimodal Agent Framework</h1>
  2. <p align="center"><b>English</b> | <a href="README_CN.md">δΈ­ζ–‡</a></p>
  3. <p align="center">✨ 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.</p>
  4. ![](docs/readme-1.png)
  5. https://github.com/user-attachments/assets/65422cef-96f9-44fe-a82b-6a124674c417
  6. ## πŸ“‹ Recent Updates
  7. - βœ… **2025-09-29**: Added RunningHub cloud ComfyUI support, enabling workflow execution without local GPU and ComfyUI environment
  8. - βœ… **2025-09-03**: Architecture refactoring from three services to unified application; added CLI tool support; published to [PyPI](https://pypi.org/project/pixelle/)
  9. - βœ… **2025-08-12**: Integrated the LiteLLM framework, adding multi-model support for Gemini, DeepSeek, Claude, Qwen, and more
  10. ## πŸš€ Features
  11. - βœ… πŸ”„ **Full-modal Support**: Supports TISV (Text, Image, Sound/Speech, Video) full-modal conversion and generation
  12. - βœ… πŸš€ **Dual Execution Modes**: Local ComfyUI self-hosted environment + RunningHub cloud ComfyUI service, users can flexibly choose based on their needs
  13. - βœ… 🧩 **ComfyUI Ecosystem**: Built on [ComfyUI](https://github.com/comfyanonymous/ComfyUI), inheriting all capabilities from the open ComfyUI ecosystem
  14. - βœ… πŸ”§ **Zero-code Development**: Defines and implements the Workflow-as-MCP Tool solution, enabling zero-code development and dynamic addition of new MCP Tools
  15. - βœ… πŸ—„οΈ **MCP Server**: Based on the [MCP](https://modelcontextprotocol.io/introduction) protocol, supporting integration with any MCP client (including but not limited to Cursor, Claude Desktop, etc.)
  16. - βœ… 🌐 **Web Interface**: Developed based on the [Chainlit](https://github.com/Chainlit/chainlit) framework, inheriting Chainlit's UI controls and supporting integration with more MCP Servers
  17. - βœ… πŸ“¦ **One-click Deployment**: Supports PyPI installation, CLI commands, Docker and other deployment methods, ready to use out of the box
  18. - βœ… βš™οΈ **Simplified Configuration**: Uses environment variable configuration scheme, simple and intuitive configuration
  19. - βœ… πŸ€– **Multi-LLM Support**: Supports multiple mainstream LLMs, including OpenAI, Ollama, Gemini, DeepSeek, Claude, Qwen, and more
  20. ## πŸ“ Project Architecture
  21. Pixelle MCP adopts a **unified architecture design**, integrating MCP server, web interface, and file services into one application, providing:
  22. - 🌐 **Web Interface**: Chainlit-based chat interface supporting multimodal interaction
  23. - πŸ”Œ **MCP Endpoint**: For external MCP clients (such as Cursor, Claude Desktop) to connect
  24. - πŸ“ **File Service**: Handles file upload, download, and storage
  25. - πŸ› οΈ **Workflow Engine**: Supports both local ComfyUI and cloud ComfyUI (RunningHub) workflows, automatically converts workflows into MCP tools
  26. ![](docs/%20mcp_structure.png)
  27. <div id="tutorial-start" />
  28. ## πŸƒβ€β™‚οΈ Quick Start
  29. Choose the deployment method that best suits your needs, from simple to complex:
  30. ### 🎯 Method 1: One-click Experience
  31. > πŸ’‘ **Zero configuration startup, perfect for quick experience and testing**
  32. #### πŸš€ Temporary Run
  33. ```bash
  34. # First you need to install the uv environment
  35. # Start with one command, no system installation required
  36. uvx pixelle@latest
  37. ```
  38. πŸ“š **[View uvx CLI Reference β†’](docs/CLI.md#uvx-method)**
  39. #### πŸ“¦ Persistent Installation
  40. ```bash
  41. # Here you need to install it in the python3.11 environment
  42. # Install to system
  43. pip install -U pixelle
  44. # Start service
  45. pixelle
  46. ```
  47. πŸ“š **[View pip CLI Reference β†’](docs/CLI.md#pip-install-method)**
  48. After startup, it will automatically enter the **configuration wizard** to guide you through execution engine selection (ComfyUI/RunningHub) and LLM configuration.
  49. ### πŸ› οΈ Method 2: Local Development Deployment
  50. > πŸ’‘ **Supports custom workflows and secondary development**
  51. #### πŸ“₯ 1. Get Source Code
  52. ```bash
  53. git clone https://github.com/AIDC-AI/Pixelle-MCP.git
  54. cd Pixelle-MCP
  55. ```
  56. #### πŸš€ 2. Start Service
  57. ```bash
  58. # Interactive mode (recommended)
  59. uv run pixelle
  60. ```
  61. πŸ“š **[View Complete CLI Reference β†’](docs/CLI.md#uv-run-method)**
  62. #### πŸ”§ 3. Add Custom Workflows (Optional)
  63. ```bash
  64. # Copy example workflows to data directory (run this in your desired project directory)
  65. cp -r workflows/* ./data/custom_workflows/
  66. ```
  67. **⚠️ Important**: Make sure to test workflows in ComfyUI first to ensure they run properly, otherwise execution will fail.
  68. ### 🐳 Method 3: Docker Deployment
  69. > πŸ’‘ **Suitable for production environments and containerized deployment**
  70. #### πŸ“‹ 1. Prepare Configuration
  71. ```bash
  72. git clone https://github.com/AIDC-AI/Pixelle-MCP.git
  73. cd Pixelle-MCP
  74. # Create environment configuration file
  75. cp .env.example .env
  76. # Edit .env file to configure your ComfyUI address and LLM settings
  77. ```
  78. #### πŸš€ 2. Start Container
  79. ```bash
  80. # Start all services in background
  81. docker compose up -d
  82. # View logs
  83. docker compose logs -f
  84. ```
  85. ### 🌐 Access Services
  86. Regardless of which method you use, after startup you can access via:
  87. - **🌐 Web Interface**: http://localhost:9004
  88. *Default username and password are both `dev`, can be modified after startup*
  89. - **πŸ”Œ MCP Endpoint**: http://localhost:9004/pixelle/mcp
  90. *For MCP clients like Cursor, Claude Desktop to connect*
  91. **πŸ’‘ Port Configuration**: Default port is 9004, can be customized via environment variable `PORT=your_port`.
  92. ### βš™οΈ Initial Configuration
  93. On first startup, the system will automatically detect configuration status:
  94. 1. **πŸš€ Execution Engine Selection**: Choose between local ComfyUI or RunningHub cloud service
  95. 2. **πŸ€– LLM Configuration**: Configure at least one LLM provider (OpenAI, Ollama, etc.)
  96. 3. **πŸ“ Workflow Directory**: System will automatically create necessary directory structure
  97. ### 🌐 RunningHub Cloud Mode Advantages
  98. - βœ… **Zero Hardware Requirements**: No need for local GPU or high-performance hardware
  99. - βœ… **No Environment Setup**: No need to install and configure ComfyUI locally
  100. - βœ… **Ready to Use**: Register and get API key to start immediately
  101. - βœ… **Stable Performance**: Professional cloud infrastructure ensures stable execution
  102. - βœ… **Auto Scaling**: Automatically handles concurrent requests and resource allocation
  103. ### 🏠 Local ComfyUI Mode Advantages
  104. - βœ… **Full Control**: Complete control over execution environment and model versions
  105. - βœ… **Privacy Protection**: All data processing happens locally, ensuring data privacy
  106. - βœ… **Custom Models**: Support for custom models and nodes not available in cloud
  107. - βœ… **No Network Dependency**: Can work offline without internet connection
  108. - βœ… **Cost Control**: No cloud service fees for high-frequency usage
  109. **πŸ†˜ Need Help?** Join community groups for support (see Community section below)
  110. ## πŸ› οΈ Add Your Own MCP Tool
  111. ⚑ One workflow = One MCP Tool, supports two addition methods:
  112. πŸ“‹ **Method 1: Local ComfyUI Workflow** - Export API format workflow files
  113. πŸ“‹ **Method 2: RunningHub Workflow ID** - Use cloud workflow IDs directly
  114. ![](docs/workflow_to_mcp_tool.png)
  115. ### 🎯 1. Add the Simplest MCP Tool
  116. * πŸ“ Build a workflow in ComfyUI for image Gaussian blur ([Get it here](docs/i_blur_ui.json)), then set the `LoadImage` node's title to `$image.image!` as shown below:
  117. ![](docs/easy-workflow.png)
  118. * πŸ“€ Export it as an API format file and rename it to `i_blur.json`. You can export it yourself or use our pre-exported version ([Get it here](docs/i_blur.json))
  119. * πŸ“‹ Copy the exported API workflow file (must be API format), input it on the web page, and let the LLM add this Tool
  120. ![](docs/ready_to_send_en.png)
  121. * ✨ After sending, the LLM will automatically convert this workflow into an MCP Tool
  122. ![](docs/added_mcp_en.png)
  123. * 🎨 Now, refresh the page and send any image to perform Gaussian blur processing via LLM
  124. ![](docs/use_mcp_tool_en.png)
  125. ### πŸ”Œ 2. Add a Complex MCP Tool
  126. The steps are the same as above, only the workflow part differs (Download workflow: [UI format](docs/t2i_by_flux_turbo_ui.json) and [API format](docs/t2i_by_flux_turbo.json))
  127. > **Note:** When using RunningHub, you only need to input the corresponding workflow ID, no need to download and upload workflow files.
  128. ![](docs/t2i_by_flux_turbo.png)
  129. ## πŸ”§ ComfyUI Workflow Custom Specification
  130. ### 🎨 Workflow Format
  131. The system supports ComfyUI workflows. Just design your workflow in the canvas and export it as API format. Use special syntax in node titles to define parameters and outputs.
  132. ### πŸ“ Parameter Definition Specification
  133. In the ComfyUI canvas, double-click the node title to edit, and use the following DSL syntax to define parameters:
  134. ```
  135. $<param_name>.[~]<field_name>[!][:<description>]
  136. ```
  137. #### πŸ” Syntax Explanation:
  138. - `param_name`: The parameter name for the generated MCP tool function
  139. - `~`: Optional, indicates URL parameter upload processing, returns relative path
  140. - `field_name`: The corresponding input field in the node
  141. - `!`: Indicates this parameter is required
  142. - `description`: Description of the parameter
  143. #### πŸ’‘ Example:
  144. **Required parameter example:**
  145. - Set LoadImage node title to: `$image.image!:Input image URL`
  146. - Meaning: Creates a required parameter named `image`, mapped to the node's `image` field
  147. **URL upload processing example:**
  148. - Set any node title to: `$image.~image!:Input image URL`
  149. - Meaning: Creates a required parameter named `image`, system will automatically download URL and upload to ComfyUI, returns relative path
  150. > πŸ“ Note: `LoadImage`, `VHS_LoadAudioUpload`, `VHS_LoadVideo` and other nodes have built-in functionality, no need to add `~` marker
  151. ### 🎯 Type Inference Rules
  152. The system automatically infers parameter types based on the current value of the node field:
  153. - πŸ”’ `int`: Integer values (e.g. 512, 1024)
  154. - πŸ“Š `float`: Floating-point values (e.g. 1.5, 3.14)
  155. - βœ… `bool`: Boolean values (e.g. true, false)
  156. - πŸ“ `str`: String values (default type)
  157. ### πŸ“€ Output Definition Specification
  158. #### πŸ€– Method 1: Auto-detect Output Nodes
  159. The system will automatically detect the following common output nodes:
  160. - πŸ–ΌοΈ `SaveImage` - Image save node
  161. - 🎬 `SaveVideo` - Video save node
  162. - πŸ”Š `SaveAudio` - Audio save node
  163. - πŸ“Ή `VHS_SaveVideo` - VHS video save node
  164. - 🎡 `VHS_SaveAudio` - VHS audio save node
  165. #### 🎯 Method 2: Manual Output Marking
  166. > Usually used for multiple outputs
  167. Use `$output.var_name` in any node title to mark output:
  168. - Set node title to: `$output.result`
  169. - The system will use this node's output as the tool's return value
  170. ### πŸ“„ Tool Description Configuration (Optional)
  171. You can add a node titled `MCP` in the workflow to provide a tool description:
  172. 1. Add a `String (Multiline)` or similar text node (must have a single string property, and the node field should be one of: value, text, string)
  173. 2. Set the node title to: `MCP`
  174. 3. Enter a detailed tool description in the value field
  175. ### ⚠️ Important Notes
  176. 1. **πŸ”’ Parameter Validation**: Optional parameters (without !) must have default values set in the node
  177. 2. **πŸ”— Node Connections**: Fields already connected to other nodes will not be parsed as parameters
  178. 3. **🏷️ Tool Naming**: Exported file name will be used as the tool name, use meaningful English names
  179. 4. **πŸ“‹ Detailed Descriptions**: Provide detailed parameter descriptions for better user experience
  180. 5. **🎯 Export Format**: Must export as API format, do not export as UI format
  181. <div id="tutorial-end" />
  182. ## πŸ’¬ Community
  183. Scan the QR codes below to join our communities for latest updates and technical support:
  184. | Discord Community | WeChat Group |
  185. | :----------------------------------------------------------: | :----------------------------------------------------------: |
  186. | <img src="docs/discord.png" alt="Discord Community" width="250" /> | <img src="docs/wechat.png" alt="WeChat Group" width="250" /> |
  187. ## 🀝 How to Contribute
  188. We welcome all forms of contribution! Whether you're a developer, designer, or user, you can participate in the project in the following ways:
  189. ### πŸ› Report Issues
  190. * πŸ“‹ Submit bug reports on the [Issues](https://github.com/AIDC-AI/Pixelle-MCP/issues) page
  191. * πŸ” Please search for similar issues before submitting
  192. * πŸ“ Describe the reproduction steps and environment in detail
  193. ### πŸ’‘ Feature Suggestions
  194. * πŸš€ Submit feature requests in [Issues](https://github.com/AIDC-AI/Pixelle-MCP/issues)
  195. * πŸ’­ Describe the feature you want and its use case
  196. * 🎯 Explain how it improves user experience
  197. ### πŸ”§ Code Contributions
  198. #### πŸ“‹ Contribution Process
  199. 1. 🍴 Fork this repo to your GitHub account
  200. 2. 🌿 Create a feature branch: `git checkout -b feature/your-feature-name`
  201. 3. πŸ’» Develop and add corresponding tests
  202. 4. πŸ“ Commit changes: `git commit -m "feat: add your feature"`
  203. 5. πŸ“€ Push to your repo: `git push origin feature/your-feature-name`
  204. 6. πŸ”„ Create a Pull Request to the main repo
  205. #### 🎨 Code Style
  206. * 🐍 Python code follows [PEP 8](https://pep8.org/) style guide
  207. * πŸ“– Add appropriate documentation and comments for new features
  208. ### 🧩 Contribute Workflows
  209. * πŸ“¦ Share your ComfyUI workflows with the community
  210. * πŸ› οΈ Submit tested workflow files
  211. * πŸ“š Add usage instructions and examples for workflows
  212. ## πŸ™ Acknowledgements
  213. ❀️ Sincere thanks to the following organizations, projects, and teams for supporting the development and implementation of this project.
  214. * 🧩 [ComfyUI](https://github.com/comfyanonymous/ComfyUI)
  215. * πŸ’¬ [Chainlit](https://github.com/Chainlit/chainlit)
  216. * πŸ”Œ [MCP](https://modelcontextprotocol.io/introduction)
  217. * 🎬 [WanVideo](https://github.com/Wan-Video/Wan2.1)
  218. * ⚑ [Flux](https://github.com/black-forest-labs/flux)
  219. * πŸ€– [LiteLLM](https://github.com/BerriAI/litellm)
  220. ## License
  221. This project is released under the MIT License ([LICENSE](LICENSE), SPDX-License-identifier: MIT).
  222. ## ⭐ Star History
  223. [![Star History Chart](https://api.star-history.com/svg?repos=AIDC-AI/Pixelle-MCP&type=Date)](https://star-history.com/#AIDC-AI/Pixelle-MCP&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.