comfyui-mcp

A Model Context Protocol(MCP) server that exposes ComfyUI workflows as callable MCP tools. Built using FastMCP and comfyui-utils.

---

Installation

Contents of this package require Python 3.11 or higher.

pip install comfyui-mcp

---

Quick Start

mcpo --port 8000 --api-key "AwesomeKey" -- python3 -m comfyui_mcp.server

Arguments

ComfyUI Connection (--comfyui.*)

• --comfyui.host (default: 127.0.0.1:8188) - ComfyUI host and port
• --comfyui.request_timeout (default: 5) - Timeout in seconds for ComfyUI API requests
• --comfyui.use_remote_workflow (default: True) - Pull workflows from ComfyUI API (True) or load from local directory (False)
• --comfyui.workflow_directory (default: workflows) - Local directory path for workflow JSON files

Output Formatting (--generate.*)

• --generate.audio_url_template - Template for audio output URLs (vars: {index}, {url})
• --generate.image_url_template - Template for image output URLs (vars: {index}, {url})
• --generate.unknown_url_template - Template for unknown output types (vars: {index}, {url})
• --generate.nothing_generated_message - Message when workflow executes but produces no output
• --generate.reply_include_workflow (default: True) - Include executed workflow parameters in response
• --generate.reply_workflow_format_indent (default: 2) - JSON indentation for workflow output
• --generate.reply_workflow_format_sort_keys (default: True) - Sort JSON keys in workflow output
• --generate.reply_workflow_template - Template for workflow parameters section (vars: {workflow_params})
• --generate.result_generated_message_template - Overall message template (vars: {image_list})

---

Architecture Overview

src/comfyui_mcp/

• __about__.py: Version and license metadata
• argument_parser.py: CLI argument definitions using pydantic
• base_types.py: Shared type aliases
• function_utils.py: Dynamic function wrapper generation
• workflow_loader.py: Load workflows from disk or ComfyUI API
• workflow_utils.py: Workflow preparation and invocation
• server.py: FastMCP server entry point

How It Works

1. Workflow Preparation:

   • For local workflows: Export your ComfyUI workflow in API format (use "Save (API Format)" in ComfyUI's menu). Place the JSON file in your configured workflows directory.
   • For remote workflows: Build and save your workflow in ComfyUI, then start or restart the MCP server. The server will automatically fetch and register available workflows from the ComfyUI instance.

2. Tool Registration: The server parses workflow JSON and automatically detects parameters by scanning for:

   • Primitive nodes (PrimitiveFloat, PrimitiveInt, PrimitiveString, etc.) - extracted as typed parameters
   • LoadImageOutput nodes - exposed as image input parameters
   • Node titles (from _meta.title) become the parameter names in the MCP tool

3. Workflow Execution: When a tool is invoked:

   • User-provided parameters are mapped back to their corresponding primitive nodes
   • The workflow is deep-copied and parameter values are injected into inputs.value fields
   • The prepared workflow is submitted to ComfyUI's API
   • Results are polled until completion
   • Generated outputs are returned as accessible URLs (format is user-configurable)

4. Batch Processing: Supports submit_batch parameter for generating multiple variations:

   • Automatically randomizes seeds for each generation
   • Executes workflows sequentially
   • Collects and returns all results together

---

Development

pip setup -hatch
hatch test
hatch build
hatch run release

---

Contributing

1. Fork the repo on GitHub.
2. Make changes, add tests, and build
3. Run hatch test to ensure all passes
4. Submit a PR