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

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