ComfyUI MCP Server

Status: Active Development Governance: Strict Compliance Protocols Active (See /docs)

A generic, Governance-Driven Model Context Protocol (MCP) server for ComfyUI. This server acts as a "Dynamic Tool Factory," automatically converting ComfyUI workflows (.json) into strongly-typed AI tools that any LLM (Claude, Flowise, etc.) can use.

🚀 Core Features

• Dynamic Tool Factory: Simply drop a workflow JSON into ./workflows/, and it becomes a native Python tool (e.g., generate_cyberpunk(seed: int)).
• Smart Injection: Maps abstract arguments to specific ComfyUI nodes using the MCP_Config convention.
• Dual Discovery: Exposes capabilities as both Resources (comfy://list) and Tools (list_workflows) for maximum client compatibility (ADR-003).
• Governance-Driven: Built by AI, for AI. The codebase is managed through a strict set of documentation rules and context boundaries.

📂 Governance Structure

This project follows a strict Governance-Driven Development (GDD) workflow. The documentation is the single source of truth.

/comfy-mcp-server
├── docs/
│   ├── governance/            # The "Efficiency Layer" (Token budgets, Context maps)
│   ├── features/              # The "Requirements" (F001, F002)
│   ├── architecture/          # The "Blueprints" (ADRs, C4 Diagrams)
│   └── implementation/        # The "Execution" (Plans, Logs, Rules)
└── workflows/                 # Drop ComfyUI JSONs here

🛠️ Quick Start

1. Prerequisites

• Python 3.10+
• ComfyUI running locally (default: http://127.0.0.1:8188)
• Node.js (Optional, for MCP Inspector)

2. Installation

# Clone repository
git clone https://github.com/your-repo/comfy-mcp-server.git
cd comfy-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install dependencies (Strictly pinned in tech_stack.md)
pip install "mcp[cli]>=1.2.0" "pydantic>=2.10.0" "makefun>=1.15.0" "fastapi>=0.115.0" "uvicorn>=0.34.0" requests websocket-client

3. Usage

SSE Mode (Recommended for Flowise/Web)

chmod +x start_sse.sh
./start_sse.sh

The server will be available at http://localhost:8000/sse.

Stdio Mode (For Claude Desktop)

./venv/bin/python server.py

🤖 Client Configuration (Flowise/Claude)

SSE Setup (Flowise)

1. Use the MCP Tool node in Flowise.
2. Set the SSE URL to http://localhost:8000/sse.
3. Add the following System Message to your agent:

   "Always call list_available_workflows first to discover tools. Use the keyword LAST in image parameters to refer to the previously generated image."

🧩 Workflow Convention

To make a ComfyUI workflow compatible, add a Note node titled MCP_Config with the following JSON format:

{
  "name": "generate_art",
  "description": "Generates art based on a prompt.",
  "parameters": [
    {
      "name": "prompt",
      "type": "string",
      "description": "What to draw",
      "target": "MCP_Positive",
      "required": true
    },
    {
      "name": "seed",
      "type": "int",
      "description": "Random seed",
      "target": "MCP_Sampler",
      "required": false
    }
  ]
}

1. Target Nodes: Ensure the nodes in your ComfyUI workflow have Titles matching the target field in your JSON (e.g., Rename a KSampler to MCP_Sampler).
2. Export: Export your workflow in API Format (JSON) and save it to the ./workflows/ directory.

See docs/architecture/adr/ADR-002-workflow-convention.md for details.