<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> &bull;
  <a href="#setup">Setup</a> &bull;
  <a href="#what-you-can-do">What You Can Do</a> &bull;
  <a href="#configuration">Configuration</a> &bull;
  <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](https://modelcontextprotocol.io/) (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

```bash
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:

```bash
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`:

```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

```bash
pytest
```

### Lint and type check

```bash
ruff check src/ tests/
mypy src/
```

### Run the server directly

```bash
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](https://modelcontextprotocol.io/) -- Model Context Protocol
- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) -- Node-based Stable Diffusion UI
- [Pydantic](https://docs.pydantic.dev/) -- Data validation
- [httpx](https://www.python-httpx.org/) -- Async HTTP client

## License

MIT