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