# ComfyUI MCP Server
A Model Context Protocol (MCP) server that enables Claude Desktop to interact with your local ComfyUI installation for AI-powered image generation.
## Features
- **15 MCP Tools** for complete ComfyUI control
- **Template-based generation** (Flux, SD1.5, SDXL, img2img)
- **Custom workflow execution** with smart parameter overrides
- **Real-time progress monitoring** via WebSocket
- **Model management** (list checkpoints, LoRAs, VAEs, etc.)
- **Workflow library** for saving and reusing workflows
- **Queue management** (status, cancel, clear)
- **Image upload/retrieval** with full Windows path support
## Prerequisites
- **Node.js** v20 or higher
- **ComfyUI** installed and running at `http://127.0.0.1:8188`
- **Claude Desktop** (for MCP integration)
- **Windows 11** (as per specification)
## Installation
### 1. Install Dependencies
> [!NOTE]
> The file paths in the examples below must be replaced with the correct paths for your system.
```bash
cd [Path to your ComfyUI MCP Server]
npm install
```
### 2. Configure Paths
Edit `config.json` to match your ComfyUI installation:
```json
{
"comfyui": {
"installation_path": "[Path to your ComfyUI portable installation]"
}
}
```
### 3. Build the Server
```bash
npm run build
```
### 4. Configure Claude Desktop
Edit `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"comfyui": {
"command": "node",
"args": [
"[Path to your ComfyUI MCP Server]\\dist\\index.js"
],
"env": {
"COMFYUI_CONFIG": "[Path to your ComfyUI MCP Server]\\config.json"
}
}
}
}
```
### 5. Restart Claude Desktop
The ComfyUI tools will now be available in Claude Desktop.
## Available Tools
### Generation
- `comfy_submit_workflow` - Submit custom workflow JSON with overrides
- `comfy_generate_simple` - Quick generation using templates
### Status & Monitoring
- `comfy_get_status` - Check generation status and outputs
- `comfy_wait_for_completion` - Wait for generation to complete
### Model Management
- `comfy_list_models` - List available models, LoRAs, VAEs
### Workflow Library
- `comfy_save_workflow` - Save workflow to library
- `comfy_load_workflow` - Load saved workflow
- `comfy_list_workflows` - List all saved workflows
- `comfy_delete_workflow` - Delete workflow from library
### Queue Management
- `comfy_get_queue` - Get current queue status
- `comfy_cancel_generation` - Cancel generation
- `comfy_clear_queue` - Clear pending queue items
### Utilities
- `comfy_upload_image` - Upload image to ComfyUI input folder
- `comfy_get_output_images` - List recent output images
## Usage Examples
### Simple Text-to-Image Generation
Ask Claude:
```
Generate an image of a sunset over mountains using Flux
```
Claude will use `comfy_generate_simple` with the flux_txt2img template.
### Custom Workflow Execution
```
Use my chrono_edit workflow to animate this product image
```
Claude will:
1. Load your workflow with `comfy_load_workflow`
2. Upload the image with `comfy_upload_image`
3. Submit with `comfy_submit_workflow` and parameter overrides
### Check Available Models
```
What Flux models do I have available?
```
Claude will use `comfy_list_models` with filter="flux".
## Configuration
### Template Defaults
Edit `config.json` to customize template defaults:
```json
{
"templates": {
"flux_txt2img": {
"default_model": "flux_dev.safetensors",
"default_steps": 20,
"default_cfg": 3.5
}
}
}
```
### Workflow Library Path
Workflows are saved to:
```
[Path to your ComfyUI portable installation]\ComfyUI\user\default\workflows\mcp_library
```
## Troubleshooting
### "Cannot connect to ComfyUI"
- Ensure ComfyUI is running: `run_nvidia_gpu.bat`
- Check ComfyUI is accessible at `http://127.0.0.1:8188`
- Verify port 8188 is not blocked by firewall
### "Model not found"
- Run `comfy_list_models` to see available models
- Check model file exists in the correct folder
- Verify model name spelling matches exactly
### "Workflow validation failed"
- Test workflow in ComfyUI UI first
- Check all node connections are valid
- Ensure all required models are available
### Permission Errors
- Check folder permissions on ComfyUI directories
- Run Claude Desktop as administrator if needed
- Verify paths in `config.json` are accessible
## Development
### Build in Watch Mode
```bash
npm run dev
```
### Clean Build
```bash
npm run clean
npm run build
```
## Architecture
```
Claude Desktop (stdio) → MCP Server → ComfyUI API (HTTP/WebSocket)
↓
File System
- Models
- Input/Output
- Workflow Library
```
The MCP server runs as a separate Node.js process and communicates with ComfyUI via its HTTP API and WebSocket connections. It does **not** modify any ComfyUI files.
## License
MIT
## Support
For issues and questions, refer to the specification document or ComfyUI API documentation.