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
# 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:
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:
{
"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
pytest
Linting and Type Checking
ruff check src/ tests/
mypy src/
Running the Server Directly
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