# ComfyUI MCP Server
An MCP (Model Context Protocol) server that lets Claude generate images using a local ComfyUI instance. Run Stable Diffusion, SDXL, and other models through natural conversation.
## Prerequisites
- **Python 3.11+**
- **ComfyUI** running locally (default: `http://127.0.0.1:8188`)
- At least one checkpoint model installed in ComfyUI
## Installation
```bash
# Clone the repository
git clone https://github.com/MatthewSnow2/comfyui-mcp-server.git
cd comfyui-mcp-server
# Create virtual environment and install
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
pip install -e ".[dev]"
```
## Configuration
Copy `.env.example` to `.env` and adjust as needed:
```bash
cp .env.example .env
```
Available environment variables (all prefixed with `COMFYUI_`):
| Variable | Default | Description |
|----------|---------|-------------|
| `COMFYUI_URL` | `http://127.0.0.1:8188` | ComfyUI server URL |
| `COMFYUI_OUTPUT_DIR` | `~/comfyui-output` | Local directory for saved images |
| `COMFYUI_DEFAULT_MODEL` | `sd_xl_base_1.0.safetensors` | Default checkpoint model |
| `COMFYUI_DEFAULT_STEPS` | `20` | Default sampling steps |
| `COMFYUI_DEFAULT_WIDTH` | `1024` | Default image width |
| `COMFYUI_DEFAULT_HEIGHT` | `1024` | Default image height |
| `COMFYUI_DEFAULT_CFG_SCALE` | `7.0` | Default CFG scale |
## Claude Desktop Setup
Add this to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"comfyui": {
"command": "/path/to/comfyui-mcp-server/.venv/bin/comfyui-mcp",
"env": {
"COMFYUI_URL": "http://127.0.0.1:8188",
"COMFYUI_DEFAULT_MODEL": "sd_xl_base_1.0.safetensors"
}
}
}
}
```
Replace `/path/to/comfyui-mcp-server` with the actual path to your installation.
**Config file locations:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
## Available Tools
### generate_image
Generate an image from a text prompt.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | (required) | Text prompt describing the image |
| `negative_prompt` | string | `""` | Things to avoid |
| `model` | string | config default | Checkpoint model name |
| `width` | int | `1024` | Image width in pixels |
| `height` | int | `1024` | Image height in pixels |
| `steps` | int | `20` | Sampling steps |
| `cfg_scale` | float | `7.0` | Classifier-free guidance scale |
| `seed` | int | `-1` | Random seed (-1 for random) |
### list_models
List all available checkpoint models installed in ComfyUI. No parameters.
### get_queue_status
Get the current ComfyUI queue status (pending, running, completed counts). No parameters.
### get_generation
Look up details of a previous generation by its prompt ID.
| Parameter | Type | Description |
|-----------|------|-------------|
| `prompt_id` | string | The prompt ID from generate_image |
## Usage Examples
Once configured in Claude Desktop, use natural language:
```
You: Generate a photo of a mountain landscape at sunset
Claude: [calls generate_image with prompt="a photo of a mountain landscape
at sunset, golden hour lighting, dramatic clouds"]
Generated successfully in 12.5s.
Image: ComfyUI-MCP_00042.png
You: What models do I have available?
Claude: [calls list_models]
You have 3 checkpoint models:
- sd_xl_base_1.0.safetensors
- dreamshaper_8.safetensors
- realisticVision_v51.safetensors
You: Generate a portrait using dreamshaper at 512x768
Claude: [calls generate_image with model="dreamshaper_8.safetensors",
width=512, height=768, prompt="..."]
Done! Image: ComfyUI-MCP_00043.png
```
## Development
### Running Tests
```bash
pytest
```
### Linting and Type Checking
```bash
ruff check src/ tests/
mypy src/
```
### Running the Server Directly
```bash
python -m src.server
```
## Architecture
```
Claude Desktop / Claude Code
|
v
MCP Server (stdio)
|
v
ComfyUI REST API (http://127.0.0.1:8188)
|
v
Stable Diffusion / SDXL model
```
The server translates MCP tool calls into ComfyUI workflow submissions, polls for completion, and returns results.
## License
MIT
