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.

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

1. 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)

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