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