A lightweight Python server implementing the Model Context Protocol (MCP) for local ComfyUI instances. It enables AI agents to generate and iteratively refine AI images, audio, and video through conversational commands, offering a powerful integration layer for creative AI workflows. The server acts as a bridge, translating natural language agent requests into ComfyUI operations and returning asset information.

How It Works

This project provides a server that delegates execution to a local ComfyUI instance via its API. It utilizes a streamable HTTP transport and has evolved from a simple request/response model to support stateful control loops. This allows for iterative refinement of generated assets, explicit asset management using stable identifiers, and asynchronous job polling and cancellation. A key feature is the automatic discovery and exposure of ComfyUI workflows as callable MCP tools, with parameters exposed via PARAM_* placeholders.

Quick Start & Requirements

1. Clone the repository: git clone https://github.com/joenorton/comfyui-mcp-server.git
2. Install dependencies: pip install -r requirements.txt
3. Ensure ComfyUI is installed and running locally (default port 8188).
4. Start the MCP server: python server.py
5. Verify with the test client: python test_client.py

Prerequisites: Python 3.8+, ComfyUI installation, and necessary ComfyUI models. Integration with AI agents requires a .mcp.json configuration file.

Highlighted Details

• Iterative Refinement: Supports regenerate tool for modifying existing assets with parameter overrides.
• Asset Identity: Uses stable (filename, subfolder, type) identifiers instead of ephemeral URLs for robust asset tracking.
• Job Management: Provides tools (get_queue_status, get_job, cancel_job) for asynchronous awareness and control over ComfyUI tasks.
• Workflow Integration: Auto-discovers custom ComfyUI workflows placed in the workflows/ directory and exposes them as tools.
• Publishing: Includes a publish_asset tool for deploying generated assets to a project's web directory, with options for deterministic compression and manifest updates.

Maintenance & Community

The project is maintained by @joenorton, with contributions noted from @venetanji for foundational components. No explicit community channels (like Discord/Slack) or roadmap links are provided in the README.

Licensing & Compatibility

Licensed under the Apache License 2.0. This license is permissive and generally compatible with commercial use and linking within closed-source projects.

Limitations & Caveats

Asset identifiers (asset_id) are session-scoped and ephemeral, expiring after 24 hours by default and becoming invalid upon server restart. The regenerate tool will fail for assets from previous sessions. The view_image tool is limited to image formats (PNG, JPEG, WebP, GIF) and does not support audio or video. The server binds to localhost by default and requires additional security measures (authentication or reverse proxy) if exposed publicly.