ComfyUI MCP Server

An MCP (Model Context Protocol) server that enables AI assistants like Claude to generate images using ComfyUI.

By Sumit Chatterjee

Features

• Generate Images: Create images from text prompts using your ComfyUI workflow
• Automatic File Handling: Optionally copy generated images directly to your project
• Status Checking: Verify ComfyUI is running before generating
• List Images: Browse previously generated images

Prerequisites

1. ComfyUI running locally on http://127.0.0.1:8188
2. Z-Image Turbo model (or modify workflow.json for your model)
3. Python 3.10+
4. Claude Code or another MCP-compatible client

Installation

1. Clone the repository

git clone https://github.com/sumitchatterjee13/comfyui-mcp-server.git

2. Install dependencies

cd path/to/comfyui-mcp
pip install -r requirements.txt

Or with uv (recommended):

uv pip install -r requirements.txt

3. Configure your MCP client

Add this server to your MCP client configuration. Examples for popular clients below.

Claude Code — global config (~/.claude.json):

{
  "mcpServers": {
    "comfyui": {
      "command": "python",
      "args": [
        "C:/Users/YourName/mcp-servers/comfyui-mcp/server.py",
        "--comfyui-url", "http://127.0.0.1:8188"
      ]
    }
  }
}

Claude Code — project-level config (.mcp.json in your project root):

{
  "mcpServers": {
    "comfyui": {
      "command": "python",
      "args": [
        "C:/Users/YourName/mcp-servers/comfyui-mcp/server.py",
        "--comfyui-url", "http://127.0.0.1:8188"
      ]
    }
  }
}

Cursor / Kilo Code / Cline / Roo Code — MCP settings JSON:

{
  "mcpServers": {
    "comfyui": {
      "command": "python",
      "args": [
        "server.py",
        "--comfyui-url", "http://127.0.0.1:8188"
      ],
      "cwd": "C:/Users/YourName/mcp-servers/comfyui-mcp",
      "alwaysAllow": [
        "generate_image",
        "batch_generate_images",
        "check_batch_status",
        "list_generated_images",
        "check_comfyui_status",
        "convert_to_webp",
        "batch_convert_to_webp"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "comfyui": {
      "command": "python",
      "args": [
        "C:/Users/YourName/mcp-servers/comfyui-mcp/server.py",
        "--comfyui-url", "http://127.0.0.1:8188"
      ]
    }
  }
}

Notes:

• Replace the paths with the actual location of your comfyui-mcp folder.
• --comfyui-url is optional (defaults to http://127.0.0.1:8188). Use it to point to ComfyUI on a different port, a LAN machine (http://192.168.1.50:8188), or a cloud instance.
• The URL can also be set via the COMFYUI_URL environment variable.
• alwaysAllow is supported by Cursor/Kilo Code/Cline/Roo Code to auto-approve tool calls without prompting each time.
• cwd lets you use a relative path for server.py instead of an absolute one.

Usage

Once configured, you can ask Claude to generate images naturally:

Basic generation

"Generate an image of a sunset over mountains"

With specific dimensions

"Create a 1920x1080 hero banner image of a modern tech office"

Save to project

"Generate a product mockup image and save it to ./public/images/product.png"

Check status

"Is ComfyUI running?"

List previous images

"Show me the last 5 images I generated"

Available Tools

generate_image

Generate an image from a text prompt.

Parameters:

Parameter	Type	Default	Description
prompt	string	required	Description of the image to generate
save_path	string	required	Full output path (no extension, forward slashes)
width	int	1024	Image width in pixels (256-4096)
height	int	1024	Image height in pixels (256-4096)
seed	int	random	Seed for reproducible generation
file_format	string	"jpg"	Output format: jpg, webp, or png

batch_generate_images

Queue multiple images (up to 100) for generation. This tool is non-blocking — it queues all images to ComfyUI and returns a batch_id immediately. Use check_batch_status to monitor progress.

Parameters:

Parameter	Type	Default	Description
images	list	required	Array of 1-100 image requests (see below)

Each image request:

Parameter	Type	Default	Description
prompt	string	required	Description of the image
save_path	string	required	Unique output path (no extension)
width	int	1024	Image width in pixels (256-4096)
height	int	1024	Image height in pixels (256-4096)
seed	int	random	Seed for reproducible generation
file_format	string	"jpg"	Output format: jpg, webp, or png

Two-step workflow:

1. Call batch_generate_images → returns batch_id immediately
2. Call check_batch_status with the batch_id → returns progress
3. Repeat step 2 until status is "completed"

Example usage:

"Generate 5 product images for the e-commerce site: a leather bag, sneakers, a watch, sunglasses, and a jacket"

check_batch_status

Check the progress of a batch image generation job. Returns current status, completed count, pending count, and results of finished images.

Parameters:

Parameter	Type	Default	Description
batch_id	string	required	The batch_id from batch_generate_images

list_generated_images

List recently generated images.

Parameters:

Parameter	Type	Default	Description
directory	string	required	Directory path to list images from
limit	int	10	Maximum images to return

check_comfyui_status

Check if ComfyUI is running and accessible. No parameters needed.

Workflow Customization

The included workflow.json is configured for the Z-Image Turbo model. To use a different workflow:

1. Export your workflow from ComfyUI (Save → API Format)
2. Replace workflow.json
3. Update the node mappings in server.py if needed:
   • Node 7: Positive prompt (text field)
   • Node 11: Dimensions (width, height fields)
   • Node 6: Seed (seed field)
   • Node 12: Output (filename_prefix field)

Troubleshooting

"Cannot connect to ComfyUI"

• Ensure ComfyUI is running
• Check it's accessible at http://127.0.0.1:8188
• Verify no firewall is blocking the connection

"Image file not found"

• Check that the save_path directory exists or is writable
• Verify ComfyUI has write permissions to the output folder

Generation seems stuck

• Check ComfyUI's web interface for errors
• Verify your model and VAE are loaded correctly
• The default timeout is 300 seconds (5 minutes)

Tips for Better Results

The Z-Image Turbo model responds well to:

1. Detailed descriptions: "A serene mountain lake at golden hour, snow-capped peaks reflected in still water, photorealistic"

2. Style specifications: "...in the style of watercolor illustration" or "...digital art, trending on artstation"

3. Composition guidance: "wide angle shot", "close-up portrait", "bird's eye view"

4. Lighting details: "dramatic lighting", "soft diffused light", "backlit silhouette"

Since this model doesn't use negative prompts, focus on describing what you want rather than what you don't want.

License

MIT License - feel free to modify and share.