MCP 服务器

ComfyUI MCP Server

Enables orchestration of ComfyUI workflows through natural language by discovering workflow templates, applying mutations, and submitting prompts to running ComfyUI instances. Provides asset validation and lightweight tooling for AI image generation experimentation.

README

ComfyUI MCP Server

An experimental Model Context Protocol (MCP) server that orchestrates ComfyUI workflows. The runtime discovers workflow templates, validates model assets, lets you tweak high-level parameters, and submits prompts to a running ComfyUI instance.

Workflow discovery – load JSON templates from a directory hierarchy and expose human-readable summaries.
Asset cataloguing – scan checkpoints, LoRAs, VAEs, text encoders, and embeddings so MCP clients can target valid resources.
High-level mutations – update prompts, samplers, LoRA stacks, and resolution bounds without hand editing graph JSON.
Execution tooling – run workflows through the ComfyUI API with optional live streaming of prompt updates.

Prerequisites

Python 3.11+
A running ComfyUI instance reachable over HTTP (defaults to http://127.0.0.1:8188)
Access to the workflow JSON templates and any model asset directories you plan to expose

Installation

Clone the repository

git clone https://github.com/<your-org>/ComfyUI_MCP.git
cd ComfyUI_MCP

Create an isolated environment (recommended)

python -m venv .venv
source .venv/bin/activate
# or use uv: uv venv

Install the package

pip install -e .
# or: uv pip install --editable .

This installs two console scripts:

comfyui-mcp – helper CLI for inspecting assets and workflows
comfyui-mcp-serve – FastMCP runtime that exposes MCP tools over stdio, SSE, or streamable HTTP

Configuration

Configuration is provided via a TOML file. Start by copying the example file and customising the values:

cp config.example.toml ~/.config/comfyui-mcp.toml

Example configuration

# ~/.config/comfyui-mcp.toml
base_url = "http://127.0.0.1:8188"
# default_workflow = "basic_workflow"

[directories]
# Each value maps to a ComfyUI model API endpoint or folder name that can be
# queried remotely. Supply fully qualified endpoints ("/models/checkpoints")
# or the folder alias returned by ``GET /models`` ("checkpoints", "vae", etc.).
checkpoints = "/models/checkpoints"
loras = "/models/loras"
vaes = "/models/vae"
text_encoders = "/models/clip"
embeddings = "/models/embeddings"

[default_bounds]
cfg_min = 1.0
cfg_max = 20.0
steps_min = 1
steps_max = 150
width_min = 128
width_max = 2048
height_min = 128
height_max = 2048

[feature_toggles]
# enable_streaming controls live prompt updates when executing workflows
enable_streaming = true
# enable_batch_execution toggles multi-workflow prompts (experimental)
enable_batch_execution = false
# watch_workflows rescan templates when files on disk change
watch_workflows = false

Environment overrides

Environment variables prefixed with COMFYUI_MCP_ override configuration values at runtime. Common examples:

COMFYUI_MCP_CONFIG – path to the TOML file (used by the runtime launcher)
COMFYUI_MCP_BASE_URL – override the ComfyUI HTTP endpoint
COMFYUI_MCP_DIRECTORIES_CHECKPOINTS – point to a different checkpoints folder
COMFYUI_MCP_FEATURES_WATCH_WORKFLOWS – toggle template reloading without editing the config file

CLI usage

Inspect templates and assets before wiring the server into an MCP client:

# List discovered workflow templates
comfyui-mcp list --config ~/.config/comfyui-mcp.toml --json

# Describe a template including semantic roles and graph metadata
comfyui-mcp describe basic_workflow --config ~/.config/comfyui-mcp.toml --json

# Enumerate checkpoints, LoRAs, VAEs, text encoders, and embeddings
comfyui-mcp assets --config ~/.config/comfyui-mcp.toml --json

CLI flags allow ad-hoc overrides without editing your TOML file:

comfyui-mcp list \
  --base-url http://localhost:8188 \
  --workflows-path ~/comfyui-mcp/workflows \
  --directory checkpoints=~/models/StableDiffusion \
  --json

Running the MCP server

Use comfyui-mcp-serve to expose the workflow tools to MCP clients. Choose a transport based on your integration target.

# stdio transport (ideal for IDE plugins / Cursor)
COMFYUI_MCP_CONFIG=~/.config/comfyui-mcp.toml \
  comfyui-mcp-serve --transport stdio

# Streamable HTTP transport (FastMCP HTTP gateway)
COMFYUI_MCP_CONFIG=~/.config/comfyui-mcp.toml \
  comfyui-mcp-serve --transport streamable-http --host 0.0.0.0 --port 8000

Optional flags:

--instructions – override the instruction string advertised to MCP clients
--host/--port – adjust bindings for HTTP/SSE transports

The runtime validates configured asset directories on startup and will exit with descriptive errors if any paths are missing or unreadable.

IDE / agent integration

Many MCP-aware tools (Cursor, Claude Desktop, Windsurf, etc.) accept a JSON manifest describing available servers. The snippet below embeds the ComfyUI MCP server alongside other backends using the same structure as Cursor's mcpServers configuration.

{
  "mcpServers": {
    "comfyui-control": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "--with",
        "aiohttp",
        "--with",
        "orjson",
        "--with",
        "python-dotenv",
        "--with",
        "pydantic",
        "comfyui-mcp-serve",
        "--transport",
        "stdio"
      ],
      "env": {
        "COMFYUI_MCP_CONFIG": "/data/comfy_ui_mcp/config.toml",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Adjust the COMFYUI_MCP_CONFIG path and any Python dependency flags to match your environment. When Cursor or another MCP client launches, it will spawn comfyui-mcp-serve over stdio using the configuration you supplied.

If you prefer to mirror the repository's bundled mcp.json, copy the file and tweak the command, transport, or environment variables as needed for your setup.