Generate images from Claude using your local ComfyUI setup

Installation • Setup • What You Can Do • Configuration • Development

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

ComfyUI MCP Server