ComfyUI MCP Server

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

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.

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