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

ComfyUI MCP Server