# comfy-mcp

MCP (Model Context Protocol) server for controlling a local ComfyUI instance from AI agents like [Claude Cowork](https://claude.ai/cowork) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code).

Lets an agent understand, modify, and execute ComfyUI workflows — enabling iterative AI-assisted image generation. Should work with any MCP-compatible agent, though it was built with Claude Cowork in mind.

## Features

- **Workflow understanding** — Parse workflow JSON and get a human-readable description of nodes, connections, and parameters
- **Parameter modification** — Change prompts, seeds, models, samplers, resolution, and any other workflow parameter
- **PNG workflow extraction** — Extract embedded workflow metadata from ComfyUI-generated PNG images
- **Workflow execution** — Submit workflows, track progress, and retrieve generated images inline
- **Reproducible outputs** — Output PNGs have workflow metadata embedded automatically, so images can be dragged back into ComfyUI to reproduce or tweak results with all nodes, connections, and widget values intact
- **Model discovery** — List available checkpoints, LoRAs, VAEs, ControlNet models, samplers, and schedulers
- **Image upload** — Upload input images for img2img, ControlNet, and other input-dependent workflows
- **Queue management** — Monitor, cancel, and clear the execution queue
- **Workflow storage** — Save and load workflows locally for reuse

## Platform support

Developed and tested on **Windows**. Should work on macOS and Linux but this has not been tested.

## Requirements

- Node.js 22+
- A running ComfyUI instance

## Setup

```bash
npm install
npm run build
```

## Configuration

Add to your MCP client settings. For Claude Code / Claude Cowork, add to `.claude/settings.json`:

```json
{
  "mcpServers": {
    "comfyui": {
      "command": "node",
      "args": ["C:\\path\\to\\comfy-mcp\\dist\\index.js"],
      "env": {
        "COMFYUI_HOST": "127.0.0.1:8000"
      }
    }
  }
}
```

For development, use `tsx` instead:

```json
{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["tsx", "C:\\path\\to\\comfy-mcp\\src\\index.ts"],
      "env": {
        "COMFYUI_HOST": "127.0.0.1:8000"
      }
    }
  }
}
```

Set `COMFYUI_HOST` to match your ComfyUI instance (default: `127.0.0.1:8000`).

## Tools

| Tool | Description |
|------|-------------|
| `get_system_stats` | GPU, VRAM, RAM, and system info |
| `get_object_info` | Available node types and their schemas |
| `list_models` | Checkpoints, LoRAs, VAEs, and other model files |
| `describe_workflow` | Human-readable workflow analysis |
| `set_workflow_parameters` | Modify workflow parameters by node ID |
| `search_workflow_nodes` | Find nodes by class type or title |
| `extract_workflow_from_image` | Extract workflow from PNG metadata |
| `execute_workflow` | Run a workflow and return images (with embedded metadata for reproducibility) |
| `get_execution_status` | Check job status |
| `get_execution_result` | Retrieve output images |
| `upload_image` | Upload input images to ComfyUI |
| `get_image` | Download images from ComfyUI |
| `get_queue` | View running and pending jobs |
| `cancel_execution` | Stop a running job |
| `clear_queue` | Clear all pending jobs |
| `get_history` | View execution history |
| `save_workflow` | Save workflow to local storage |
| `load_workflow` | Load a saved workflow |
| `list_workflows` | List saved workflows |

## Typical usage flow

1. Extract a workflow from a PNG or load a saved one
2. Describe the workflow to understand its structure
3. Check available models
4. Modify parameters (prompt, seed, model, etc.)
5. Execute and view the result
6. Drag the output PNG back into ComfyUI to reproduce or continue iterating

## PNG metadata

Output images automatically embed the full workflow in ComfyUI-compatible PNG metadata. This means any image generated through this server can be dragged directly into the ComfyUI canvas to restore all nodes, connections, and widget values. If you provide the original UI-format workflow (via the `ui_workflow` parameter), exact node positions and group labels are preserved; otherwise, the server auto-generates a clean left-to-right layout from the API-format workflow.

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `COMFYUI_HOST` | `127.0.0.1:8000` | ComfyUI API host and port |
| `COMFYUI_WORKFLOWS_DIR` | `~/.comfy-mcp/workflows` | Local workflow storage directory |