comfy-mcp

MCP (Model Context Protocol) server for controlling a local ComfyUI instance from AI agents like Claude Cowork or 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

npm install
npm run build

Configuration

Add to your MCP client settings. For Claude Code / Claude Cowork, add to .claude/settings.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:

{
  "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

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