ComfyUI MCP Server

An MCP (Model Context Protocol) server that connects AI assistants to ComfyUI for image, video, and audio generation. Works with Claude Desktop, Claude Code, and any MCP-compatible client.

What It Does

This server gives AI agents full control over ComfyUI — from one-call image generation to building complex multi-node workflows. It exposes 40+ tools organized into three tiers:

Quick Generation (one-call tools)

All parameters have sensible defaults. Only a prompt is required:

Tool	Description
text_to_image	Generate images from text (local SD/SDXL model)
flux_text_to_image	Generate images using Flux (auto-detects GGUF/safetensors)
image_to_image	Transform an existing image with a prompt
text_to_video	Generate video from text (local LTX-Video model)
image_to_video	Animate an image into video (LTX-Video)
wan_text_to_video	Generate video from text (local Wan 2.2 model)
wan_image_to_video	Animate an image into video (Wan 2.2)
upscale_image	AI upscale with an upscale model
inpaint	Fill masked regions with AI-generated content
dalle3_image	DALL-E 3 image generation (cloud API)
gpt_image_generate	GPT Image generation/editing (cloud API)
sora_video_generate	Sora 2 video generation (cloud API)
merge_videos	Merge multiple videos into one

Any API Node (200+ cloud providers)

Run any of ComfyUI's 200+ API nodes in a single call — Kling, Runway, Luma, Stability, ElevenLabs, Gemini, Veo, Recraft, Minimax, and more:

1. list_api_nodes(query="kling") — discover available API nodes
2. get_node_schema("KlingTextToVideoNode") — see inputs, types, defaults
3. run_api_node(node_class="KlingTextToVideoNode", inputs='{"prompt": "..."}') — execute

Automatically inserts loader nodes for image/video/audio inputs and save nodes for outputs. Validates COMBO values, INT/FLOAT ranges, and required inputs before submitting.

Supports async execution for parallel jobs:

run_api_node(..., queue_only=true)  # returns immediately with prompt_id
wait_for_jobs("id1,id2,id3")       # waits for all concurrently

Custom Workflows (multi-node graphs)

For complex workflows (ControlNet, multi-LoRA, regional prompting, IP-Adapter):

1. search_nodes(query="controlnet") — find relevant nodes
2. get_node_schema("ControlNetApplyAdvanced") — understand inputs/outputs
3. create_workflow(template="txt2img") — start from a template
4. add_node(workflow_id, "ControlNetLoader", ...) — add nodes incrementally
5. suggest_next(workflow_id) — see what's missing
6. validate_workflow(workflow_id) — check for errors
7. execute_workflow(workflow_id) — generate results

System & Utility Tools

Tool	Description
list_models	List installed models by folder (checkpoints, loras, etc.)
list_samplers_and_schedulers	List valid sampler/scheduler names
get_system_stats	ComfyUI system info (VRAM, version, etc.)
get_queue_status	Current queue state
get_history	Generation history
get_logs	Server logs
upload_image	Upload an image to ComfyUI's input directory
upload_mask	Upload a mask image for inpainting
get_image_url	Get URL to view/download generated files
list_files	List files in ComfyUI directories
copy_output_to_input	Copy generated files to input for reuse
wait_for_jobs	Wait for multiple queued jobs concurrently

Prerequisites

ComfyUI

You need a running ComfyUI instance. Install it following the official instructions.

Make sure ComfyUI is running and accessible (default: http://127.0.0.1:8188).

Models (for local generation)

For local generation tools, you need models installed in ComfyUI:

• SD/SDXL image (text_to_image): Any SD/SDXL checkpoint in models/checkpoints/
• Flux image (flux_text_to_image): A Flux diffusion model (safetensors in models/diffusion_models/ or GGUF) + clip_l.safetensors and t5xxl encoder in models/text_encoders/ + ae.safetensors VAE in models/vae/
• LTX-Video (text_to_video, image_to_video): LTX-Video checkpoint + T5-XXL text encoder
• Wan 2.2 video (wan_text_to_video, wan_image_to_video): Wan 2.2 GGUF model + umt5_xxl encoder in models/text_encoders/ + wan2.2_vae.safetensors in models/vae/
• Upscaling (upscale_image): Any upscale model in models/upscale_models/

All local tools auto-detect installed models. Use list_models() to see what's available.

Use list_models() through the MCP to see what's currently installed.

Comfy.org API Key (for cloud generation)

Cloud-based tools (dalle3_image, gpt_image_generate, sora_video_generate, run_api_node) require a Comfy.org API key with credits loaded. Set it via the COMFY_API_KEY environment variable.

Installation

From source

git clone https://github.com/halbert04/comfyui-mcp.git
cd comfyui-mcp
pip install .

For development:

pip install -e ".[dev]"

Verify installation

comfyui-mcp --help

Configuration

All configuration is via environment variables:

Variable	Default	Description
COMFYUI_URL	http://127.0.0.1:8188	ComfyUI server URL
COMFYUI_TIMEOUT	300	Max wait time for job completion (seconds)
COMFYUI_POLL_INTERVAL	1.0	Polling interval for job status (seconds)
COMFY_API_KEY	(empty)	Comfy.org API key for cloud API nodes
COMFYUI_MCP_TRANSPORT	stdio	Transport mode: stdio or streamable-http
COMFYUI_MCP_HOST	127.0.0.1	Host for HTTP transport
COMFYUI_MCP_PORT	8200	Port for HTTP transport

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "comfyui": {
      "command": "comfyui-mcp",
      "env": {
        "COMFYUI_URL": "http://127.0.0.1:8188",
        "COMFYUI_TIMEOUT": "900",
        "COMFY_API_KEY": "your-comfy-api-key-here"
      }
    }
  }
}

Restart Claude Desktop after saving. The ComfyUI tools will appear in the tool list.

Usage with Claude Code

Add the MCP server to your Claude Code configuration:

claude mcp add comfyui -- comfyui-mcp

Or with environment variables:

claude mcp add comfyui -e COMFYUI_URL=http://127.0.0.1:8188 -e COMFY_API_KEY=your-key -- comfyui-mcp

Usage as HTTP Server

For non-stdio clients, run as an HTTP server:

COMFYUI_MCP_TRANSPORT=streamable-http comfyui-mcp

This starts an MCP server on http://127.0.0.1:8200 that any MCP client can connect to.

Project Structure

src/comfyui_mcp/
  server.py          # MCP server entry point and tool registration
  client.py          # HTTP client for ComfyUI API
  config.py          # Environment variable configuration
  workflows.py       # Workflow graph builder and templates
  node_cache.py      # Cached node schema from /object_info
  polling.py         # Job completion polling
  tools/
    generate.py      # One-call generation tools
    api_runner.py    # Generic API node runner (run_api_node, list_api_nodes)
    builder.py       # Workflow builder tools (create, add_node, execute, etc.)
    discovery.py     # Node discovery tools (search_nodes, get_node_schema)
    models.py        # Model listing tools
    system.py        # System info, queue, history, file browsing
  resources/
    resources.py     # MCP resources (workflow templates, system info)

Development

Run tests:

pip install -e ".[dev]"
pytest

License

MIT