ComfyUI MCP Server

<p align="center"> <img src="assets/banner.png" alt="ComfyUI MCP Server" width="800"> </p>

<h3 align="center">Generate images from Claude using your local ComfyUI setup</h3>

<p align="center"> <a href="#installation">Installation</a> • <a href="#setup">Setup</a> • <a href="#what-you-can-do">What You Can Do</a> • <a href="#configuration">Configuration</a> • <a href="#development">Development</a> </p>

---

What is this?

ComfyUI MCP Server connects Claude Desktop (or Claude Code) to your local ComfyUI instance. Once set up, you can ask Claude to generate images and it will run them through Stable Diffusion, SDXL, or whatever checkpoint models you have installed -- no copy-pasting prompts between apps.

It works over MCP (Model Context Protocol), which means Claude treats your ComfyUI setup as a native tool.

Example conversation:

You:   Generate a watercolor painting of a coastal village at sunrise
Claude: I'll generate that using your SDXL model.
        [calls generate_image -> ComfyUI runs the workflow -> returns result]
        Done -- saved as ComfyUI-MCP_00042.png (14.2s)

How it works

Claude Desktop / Claude Code
        |
        v
  MCP Server (stdio)
        |
        v
  ComfyUI REST API (localhost:8188)
        |
        v
  Your GPU -> Stable Diffusion / SDXL / etc.

The server translates Claude's tool calls into ComfyUI workflow submissions, polls for completion, and returns the results.

Prerequisites

• Python 3.11+
• ComfyUI running locally (default: http://127.0.0.1:8188)
• At least one checkpoint model installed in ComfyUI

Installation

git clone https://github.com/MatthewSnow2/comfyui-mcp.git
cd comfyui-mcp

python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows

pip install -e ".[dev]"

Setup

1. Configure environment

Copy .env.example to .env and adjust if needed:

cp .env.example .env

Variable	Default	What it does
COMFYUI_URL	http://127.0.0.1:8188	Where your ComfyUI is running
COMFYUI_OUTPUT_DIR	~/comfyui-output	Where generated images get saved
COMFYUI_DEFAULT_MODEL	sd_xl_base_1.0.safetensors	Which checkpoint to use by default
COMFYUI_DEFAULT_STEPS	20	Sampling steps
COMFYUI_DEFAULT_WIDTH	1024	Image width (px)
COMFYUI_DEFAULT_HEIGHT	1024	Image height (px)
COMFYUI_DEFAULT_CFG_SCALE	7.0	CFG scale

2. Add to Claude Desktop

Add this block to your claude_desktop_config.json:

{
  "mcpServers": {
    "comfyui": {
      "command": "/path/to/comfyui-mcp/.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 with your actual install path.

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

3. Restart Claude Desktop

Restart the app. You should see "comfyui" listed in the MCP tools dropdown.

What you can do

Generate images

Ask Claude to generate an image from any text prompt. It handles prompt engineering, model selection, and parameter tuning.

Parameter	Type	Default	Description
prompt	string	(required)	What you want to see
negative_prompt	string	""	What to avoid
model	string	config default	Checkpoint model name
width	int	1024	Width in pixels
height	int	1024	Height in pixels
steps	int	20	Sampling steps (more = slower but often better)
cfg_scale	float	7.0	How closely to follow the prompt
seed	int	-1	Random seed (-1 = random each time)

List your models

Ask "what models do I have?" and Claude will show every checkpoint installed in your ComfyUI.

Check queue status

Ask "what's in the queue?" to see how many jobs are pending, running, or completed.

Look up past generations

Give Claude a prompt ID from a previous generation and it will pull up the details.

Real usage examples

You:   What models do I have?
Claude: You have 3 checkpoints:
        - sd_xl_base_1.0.safetensors
        - dreamshaper_8.safetensors
        - realisticVision_v51.safetensors

You:   Generate a cyberpunk street scene using dreamshaper at 512x768
Claude: [runs generation with dreamshaper_8, 512x768]
        Done -- ComfyUI-MCP_00043.png (8.3s)

You:   Same scene but make it daytime and use realisticVision
Claude: [runs generation with realisticVision_v51, same dimensions]
        Done -- ComfyUI-MCP_00044.png (9.1s)

Development

Run tests

pytest

Lint and type check

ruff check src/ tests/
mypy src/

Run the server directly

python -m src.server

Project structure

comfyui-mcp/
  src/
    server.py          # MCP server entry point
    comfyui_client.py  # HTTP client for ComfyUI API
    config.py          # Settings via pydantic-settings
    models.py          # Pydantic data models
    workflows.py       # ComfyUI workflow templates
  tests/               # pytest suite
  pyproject.toml
  README.md

Built with

• MCP SDK -- Model Context Protocol
• ComfyUI -- Node-based Stable Diffusion UI
• Pydantic -- Data validation
• httpx -- Async HTTP client

License

MIT