Content
# ComfyUI MCP Server
[English](./README_EN.md)
Wrap ComfyUI App Mode workflows into MCP tools, allowing AI assistants to query templates, execute workflows, chain multi-step generations, and handle media results like images.
If you encounter bugs or need features, please join the group `1082160486` or submit an issue.
## Suitable Scenarios
- **Expose ComfyUI capabilities to AI**: AI only needs to fill in template parameters, without understanding node graphs.
- **Reuse App Mode workflows**: Use ComfyUI frontend to mark inputs and outputs, then generate MCP templates.
- **Batch and multi-step execution**: One call can run multiple independent tasks or pass the output of one step to the next.
- **Query local models**: Support AI to query `checkpoints`, `loras`, `vae`, and other model directories.
## Quick Start
1. Install the plugin in the ComfyUI `custom_nodes` directory and install dependencies:
```bash
cd ComfyUI/custom_nodes
git clone <this-repo-url> ComfyUI-APP-MCP
cd ComfyUI-APP-MCP
python -m pip install -r requirements.txt
```
2. Start ComfyUI and ensure it supports App Mode.
3. Open a workflow, and in the top-left menu, go to **App Builder**.
4. Mark the content you want AI to modify as input, and mark nodes that save images as output. Name the inputs clearly.
5. Add a Markdown note to explain the template:
- `title`: A short title for the template, displayed in the template list.
- `description`: A detailed description of the template, displayed in the template details.
- Other titles: Optional documents that can be read on demand.
6. In **Settings → MCP Server → Templates**, click **Create from Workflow** to create a template.
7. Connect to MCP client at `http://127.0.0.1:8188/app-mcp` or `http://127.0.0.1:8189/mcp`.
8. Let AI call `list_templates()` first, then call `get_template()`, `run_template()`, or `run_templates()`.
After workflow changes, refresh the template with the same name in the settings panel. If input parameters change, remind AI to re-read the template.
If you want to automatically generate a random seed each time, name the corresponding input `seed` in App Builder. The system will automatically fill in a random value during execution, and AI doesn't need to pass this parameter.
## Connection Addresses
| Entry | Address | Description |
| ---------------- | ------------------------------- | ----------------------------------- |
| ComfyUI Proxy Entry | `http://127.0.0.1:8188/app-mcp` | Access MCP through ComfyUI port |
| MCP Direct Entry | `http://127.0.0.1:8189/mcp` | Starts with ComfyUI, usage is the same |
MCP client configuration example:
```json
{
"mcpServers": {
"comfyui": {
"url": "http://127.0.0.1:8188/app-mcp"
}
}
}
```
You can also use:
```text
http://127.0.0.1:8189/mcp
```
When accessing ComfyUI remotely, start it with `python main.py --listen`.
When accessing over LAN or remotely, replace `127.0.0.1` with the actual ComfyUI/MCP machine address. See [Standalone Deployment and Remote Access](./docs/standalone.md) for more deployment methods.
## Common Tools
| Tool | Purpose | When to Use |
| -------------------------------- | ---------------------------- | ------------------------------------ |
| `list_templates()` | List available templates | Check available capabilities before starting tasks |
| `get_template(name)` | Read template parameters, outputs, and documentation entry | Confirm parameters before execution |
| `read_template_doc(name, title)` | Read extended template documentation | When `description` mentions more documentation |
| `run_template()` | Execute a single template | Single-step tasks like text-to-image, image-to-image, enlargement, encryption |
| `run_templates()` | Run multiple tasks at once and return each step's result | Batch generation or multi-step processing |
| `upload_image(source)` | Upload a new image provided by the user | When the image comes from the user locally, URL, or base64 |
| `list_models(folder, keywords)` | Query model directories | When selecting checkpoints, LoRA, VAE |
| `get_template_result()` | Query or wait for results | When `run_template` times out or waits asynchronously |
See [Tool Reference](./docs/tools.md) for complete parameters, return structures, and examples.
## Frontend Management
In **Settings → MCP Server**, you can:
- View MCP service status and connection addresses
- Set default wait timeout for `run_template(wait=true)`
- Create, refresh, enable, disable, or delete templates
- Scan workflows and automatically create missing templates
- Batch refresh existing templates
- Export template zip for standalone deployment
See [Tool Reference: Frontend Management](./docs/tools.md#comfyui-frontend-management) for more details.
## Documentation Navigation
| Document | Content |
| --------------------------------------------- | ---------------------------------------------------- |
| [Tool Reference](./docs/tools.md) | MCP tool parameters, return formats, template chaining, image upload, model query |
| [Standalone Deployment and Remote Access](./docs/standalone.md) | Environment variables, standalone configuration, media proxy, client connection |
| [Troubleshooting](./docs/troubleshooting.md) | Template empty, output empty, image input, remote access, logs |
| [Development Notes](./docs/development.md) | Code structure, testing suggestions, development commands |
| [Documentation Index](./docs/README.md) | English and Chinese documentation entry |
## Frequently Asked Questions
### Template list is empty
Ensure the workflow is saved to the server via ComfyUI's **Save**, not just exported to local.
### Image input doesn't take effect
Upload new images with `upload_image()` first, then fill the returned `name` into template parameters. The AI can chain the images generated by the template.
### Can't find workflow when creating template
Confirm ComfyUI runs on port `8188`. The plugin reads workflows with `COMFYUI_URL=http://127.0.0.1:8188` by default. If your ComfyUI port is different:
```bash
COMFYUI_URL=http://127.0.0.1:<your-port>
```
### Can't send images after integrating with AstrBot or similar platforms
Confirm AI calls the correct parameter type when sending tools. A common mistake is filling image URLs into local file path parameters. If the platform distinguishes `url`, `image_url`, `file`, `path`, use the correct field.
