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

1. Clone the repository

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

2. Create an isolated environment (recommended)

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

3. 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.

---

Repository layout

• src/comfyui_mcp/ – server implementation, CLI, and FastMCP runtime glue
• workflows/ – example workflow templates discovered by default
• docs/ – additional design notes and reference material
• tests/ – unit tests for asset discovery and workflow mutation helpers

---

Contributing

Bug reports and pull requests are welcome! Please include reproduction steps and relevant ComfyUI versions when filing issues.

---

License

Distributed under the MIT license. See LICENSE (or the top-level repository metadata) for details.