# mcp-comfyui

MCP server bridging Claude Desktop to local and remote [ComfyUI](https://github.com/comfyanonymous/ComfyUI) instances, including [Comfy Cloud](https://cloud.comfy.org).

## Tools

| Tool | Description |
|---|---|
| `comfyui_health` | Check server reachable + response time |
| `comfyui_list_models` | List models by type (checkpoints, loras, etc.) |
| `comfyui_queue_prompt` | Queue a workflow, get prompt ID back immediately |
| `comfyui_poll_status` | Poll prompt status (queued / running / completed / error / cancelled) |
| `comfyui_get_outputs` | Get output file paths or download URLs after completion |

## Requirements

- Python 3.11+
- Local ComfyUI instance **or** a [Comfy Cloud](https://platform.comfy.org) subscription

## Install

```bash
pip install -r requirements.txt
```

## Configuration

### Server config format

Each entry in `COMFYUI_SERVERS` is either a plain URL string (local, no auth) or a dict:

```jsonc
{
  // String shorthand — local ComfyUI, no auth
  "default": "http://localhost:8188",

  // Dict — full options
  "remote": { "url": "http://192.168.1.100:8188", "mode": "local" },
  "cloud":  { "url": "https://cloud.comfy.org", "api_key": "YOUR_KEY", "mode": "cloud" }
}
```

`mode` is `"local"` (default) or `"cloud"`. `api_key` is required for Comfy Cloud.

If `COMFYUI_SERVERS` is absent, defaults to `{"default": "http://localhost:8000"}`.

### Via `.env` file

```bash
cp .env.example .env
# edit .env
```

### Via Claude Desktop config

`~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "comfyui": {
      "command": "/opt/miniconda3/bin/python3",
      "args": ["/path/to/mcp-comfyui/server.py"],
      "env": {
        "COMFYUI_SERVERS": "{\"default\": \"http://localhost:8188\", \"cloud\": {\"url\": \"https://cloud.comfy.org\", \"api_key\": \"YOUR_KEY\", \"mode\": \"cloud\"}}"
      }
    }
  }
}
```

Omit `env` to use `.env` file instead.

## Typical Workflow

1. `comfyui_health` — confirm server up
2. `comfyui_list_models` — find available checkpoints/LoRAs
3. `comfyui_queue_prompt` — submit workflow JSON, get `prompt_id`
4. `comfyui_poll_status` — repeat until `status = completed`
5. `comfyui_get_outputs` — get file paths (local) or `/api/view` download URLs (cloud)

## Mode Differences

| Behaviour | Local | Cloud |
|---|---|---|
| Health probe | `GET /system_stats` | `GET /api/queue` |
| Auth | none | `X-API-Key` header |
| Submit workflow | `POST /api/prompt` | `POST /api/prompt` |
| Poll status | `/history/{id}` + `/queue` | `/api/job/{id}/status` |
| Status values | queued / running / completed / error | + cancelled |
| Outputs | absolute filesystem paths | `/api/view?filename=…` URLs (302 → signed URL) |
| Model listing | `/api/models/{type}` → `/api/object_info` fallback | same |

## Manual Test

```bash
/opt/miniconda3/bin/python3 -c "
import asyncio
from server import comfyui_health, comfyui_list_models, ServerInput, ListModelsInput

async def main():
    print(await comfyui_health(ServerInput(server='default')))
    print(await comfyui_list_models(ListModelsInput(server='default', filter='checkpoints')))

asyncio.run(main())
"
```

## Notes

- `comfyui_queue_prompt` expects valid ComfyUI API-format workflow JSON. No validation performed.
- Local output paths built from `--output-directory` flag reported in `/system_stats`.
- Cloud outputs: caller must follow the 302 redirect from `/api/view` to reach the signed storage URL.
- Stdio transport only — this server opens no network ports.