comfyui-mcp-server
lightweight Python-based MCP (Model Context Protocol) server for local ComfyUI
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/joenorton--comfyui-mcp-server)HTML
<a href="/listings/joenorton--comfyui-mcp-server"><img src="/api/listings/joenorton--comfyui-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
This proves everything is working.
1) Clone and set up
git clone https://github.com/joenorton/comfyui-mcp-server.git cd comfyui-mcp-server pip install -r requirements.txt
2) Start ComfyUI
Make sure ComfyUI is installed and running locally.
cd <ComfyUI_dir> python main.py --port 8188
3) Run the MCP server
From the repository directory:
python server.py
The server listens at:
http://127.0.0.1:9000/mcp
4) Verify it works (no AI client required)
Run the included test client:
# Use default prompt python test_client.py # Or provide your own prompt python test_client.py -p "a beautiful sunset over mountains" python test_client.py --prompt "a cat on a mat"
`test_client.py` will:
* connect to the MCP server * list available tools * fetch and display server defaults (width, height, steps, model, etc.) * run `generate_image` with your prompt (or a default) * automatically use server defaults for all other parameters * print the resulting asset information
If this step succeeds, the system is working.
**Note:** The test client respects server defaults configured via config files, environment variables, or `set_defaults` calls. Only the `prompt` parameter is required; all other parameters use server defaults automatically.
That’s it.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 354 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # ComfyUI MCP Server
- > Generate and refine AI images/audio/video through natural conversation
- A lightweight MCP (Model Context Protocol) server that lets AI agents generate and iteratively refine images, audio, and video using a local ComfyUI instance.
- You run the server, connect a client, and issue tool calls. Everything else is optional depth.
- ---
- ## Quick Start (2–3 minutes)
- This proves everything is working.
- ### 1) Clone and set up
- ```bash
- git clone https://github.com/joenorton/comfyui-mcp-server.git
- cd comfyui-mcp-server
- pip install -r requirements.txt
- ```
- ### 2) Start ComfyUI
- Make sure ComfyUI is installed and running locally.
- ```bash
- cd <ComfyUI_dir>
- python main.py --port 8188
- ```
- ### 3) Run the MCP server
- From the repository directory:
- ```bash
- python server.py
- ```
- The server listens at:
- ```
- http://127.0.0.1:9000/mcp
- ```
- ### 4) Verify it works (no AI client required)
- Run the included test client:
- ```bash
- # Use default prompt
- python test_client.py
- # Or provide your own prompt
- python test_client.py -p "a beautiful sunset over mountains"
- python test_client.py --prompt "a cat on a mat"
- ```
- `test_client.py` will:
- * connect to the MCP server
- * list available tools
- * fetch and display server defaults (width, height, steps, model, etc.)
- * run `generate_image` with your prompt (or a default)
- * automatically use server defaults for all other parameters
- * print the resulting asset information
- If this step succeeds, the system is working.
- **Note:** The test client respects server defaults configured via config files, environment variables, or `set_defaults` calls. Only the `prompt` parameter is required; all other parameters use server defaults automatically.
- That’s it.
- ---
- ## Use with an AI Agent (Cursor / Claude / n8n)
- Once the server is running, you can connect it to an AI client.
- Create a project-scoped `.mcp.json` file:
- ```json
- {
- "mcpServers": {
- "comfyui-mcp-server": {
- "type": "streamable-http",
- "url": "http://127.0.0.1:9000/mcp"
- }
- }
- }
- ```
- **Note:** Some clients use `"type": "http"` instead of `"streamable-http"`. Both work with this server. If auto-discovery doesn't work, try changing the type field.
- Restart your AI client. You can now call tools such as:
- * `generate_image`
- * `view_image`
- * `regenerate`
- * `get_job`
- * `list_assets`
- This is the primary intended usage mode.
- ---
- ## What You Can Do After It Works
- Once you’ve confirmed the server runs and a client can connect, the system supports:
- * Iterative refinement via `regenerate` (no re-prompting)
- * Explicit asset identity for reliable follow-ups
- * Job polling and cancellation for long-running generations
- * Optional image injection into the AI’s context (`view_image`)
- * Auto-discovered ComfyUI workflows with parameter exposure
- * Configurable defaults to avoid repeating common settings
- Everything below builds on the same basic loop you just tested.
- ## Migration Notes (Previous Versions)
- If you’ve used earlier versions of this project, a few things have changed.
- ### What’s the Same
- - You still run a local MCP server that delegates execution to ComfyUI
- - Workflows are still JSON files placed in the `workflows/` directory
- - Image generation behavior is unchanged at its core
- ### What’s New
- - **Streamable HTTP transport** replaces the older WebSocket-based approach
- - **Explicit job management** (`get_job`, `get_queue_status`, `cancel_job`)
- - **Asset identity** instead of ad-hoc URLs (stable across hostname changes)
- - **Iteration support** via `regenerate` (replay with parameter overrides)
- - **Optional visual feedback** for agents via `view_image`
- - **Configurable defaults** to avoid repeating common parameters
- ### What Changed Conceptually
- Earlier versions were a thin request/response bridge.
- The current version is built around **iteration** and **stateful control loops**.
- You can still generate an image with a single call, but you now have the option to:
- - refer back to specific outputs
- - refine results without re-specifying everything
- - poll and cancel long-running jobs
- - let AI agents inspect generated images directly
- ### Looking for the Old Behavior?
- If you want the minimal, single-shot behavior from earlier versions:
- - run `test_client.py` (this mirrors the original usage pattern)
- - call `generate_image` with just a prompt (server defaults handle the rest)
- - ignore the additional tools
- No migration is required unless you want the new capabilities.
- ## Available Tools
- ### Generation Tools
- - **`generate_image`**: Generate images (requires `prompt`)
- - **`generate_song`**: Generate audio (requires `tags` and `lyrics`)
- - **`regenerate`**: Regenerate an existing asset with optional parameter overrides (requires `asset_id`)
- ### Viewing Tools
- - **`view_image`**: View generated images inline (images only, not audio/video)
- ### Job Management Tools
- - **`get_queue_status`**: Check ComfyUI queue state (running/pending jobs) - provides async awareness
- - **`get_job`**: Poll job completion status by prompt_id - check if a job has finished
- - **`list_assets`**: Browse recently generated assets - enables AI memory and iteration
- - **`get_asset_metadata`**: Get full provenance and parameters for an asset - includes workflow history
- - **`cancel_job`**: Cancel a queued or running job
- ### Configuration Tools
- - **`list_models`**: List available ComfyUI models
- - **`get_defaults`**: Get current default values
- - **`set_defaults`**: Set default values (with optional persistence)
- ### Workflow Tools
- - **`list_workflows`**: List all available workflows
- - **`run_workflow`**: Run any workflow with custom parameters
- ### Publish Tools
- - **`get_publish_info`**: Show publish status (detected project root, publish dir, ComfyUI output root, and any missing setup)
- - **`set_comfyui_output_root`**: Set ComfyUI output directory (recommended for Comfy Desktop / nonstandard installs; persisted across restarts)
- - **`publish_asset`**: Publish a generated asset into the project's web directory with deterministic compression (default 600KB)
- **Publish Notes:**
- - **Session-scoped**: `asset_id`s are valid only for the current server session; restart invalidates them.
- - **Zero-config in common cases**: Publish dir auto-detected (`public/gen`, `static/gen`, or `assets/gen`); if ComfyUI output can't be detected, set it once via `set_comfyui_output_root`.
- - **Two modes**: Demo (explicit filename) and Library (auto filename + manifest update). In library mode, `manifest_key` is required.
- - **Manifest**: Updated only when `manifest_key` is provided.
- - **Compression**: Deterministic ladder to meet size limits; fails with a clear error if it can't.
- **Quick Start:**
- Example agent conversation flow:
- **User:** "Generate a hero image for my website and publish it as hero.webp"
- **Agent:** *Checks publish configuration*
- - Calls `get_publish_info()` → sees status "ready"
- **Agent:** *Generates image*
- - Calls `generate_image(prompt="a hero image for a website")` → gets `asset_id`
- **Agent:** *Publishes asset*
- - Calls `publish_asset(asset_id="...", target_filename="hero.webp")` → success
- **User:** "Now generate a logo and add it to the manifest as 'site-logo'"
- **Agent:** *Generates and publishes with manifest*
- - Calls `generate_image(prompt="a modern logo")` → gets `asset_id`
- - Calls `publish_asset(asset_id="...", manifest_key="site-logo")` → auto-generates filename, updates manifest
- See [docs/HOW_TO_TEST_PUBLISH.md](docs/HOW_TO_TEST_PUBLISH.md) for detailed usage and testing instructions.
- ## Custom Workflows
- Add custom workflows by placing JSON files in the `workflows/` directory. Workflows are automatically discovered and exposed as MCP tools.
- ### Workflow Placeholders
- Use `PARAM_*` placeholders in workflow JSON to expose parameters:
- - `PARAM_PROMPT` → `prompt: str` (required)
- - `PARAM_INT_STEPS` → `steps: int` (optional)
- - `PARAM_FLOAT_CFG` → `cfg: float` (optional)
- **Example:**
- ```json
- {
- "3": {
- "inputs": {
- "text": "PARAM_PROMPT",
- "steps": "PARAM_INT_STEPS"
- }
- }
- }
- ```
- The tool name is derived from the filename (e.g., `my_workflow.json` → `my_workflow` tool).
- ---
- ## Configuration
- The server supports configurable defaults to avoid repeating common parameters. Defaults can be set via:
- - **Runtime defaults**: Use `set_defaults` tool (ephemeral, lost on restart)
- - **Config file**: `~/.config/comfy-mcp/config.json` (persistent)
- - **Environment variables**: `COMFY_MCP_DEFAULT_*` prefixed variables
- Defaults are resolved in priority order: per-call values → runtime defaults → config file → environment variables → hardcoded defaults.
- For complete configuration details, see [docs/REFERENCE.md](docs/REFERENCE.md#parameters).
- ---
- ## Detailed Reference
- Complete parameter lists, return schemas, configuration options, and advanced workflow metadata are documented in:
- - **[API Reference](docs/REFERENCE.md)** - Complete tool reference, parameters, return values, and configuration
- - **[Architecture](docs/ARCHITECTURE.md)** - Design decisions and system overview
- ## Project Structure
- ```
- comfyui-mcp-server/
- ├── server.py # Main entry point
- ├── comfyui_client.py # ComfyUI API client
- ├── asset_processor.py # Image processing utilities
- ├── test_client.py # Test client
- ├── managers/ # Core managers
- │ ├── workflow_manager.py
- │ ├── defaults_manager.py
- │ └── asset_registry.py
- ├── tools/ # MCP tool implementations
- │ ├── generation.py
- │ ├── asset.py
- │ ├── job.py # Job management tools
- │ ├── configuration.py
- │ └── workflow.py
- ├── models/ # Data models
- │ ├── workflow.py
- │ └── asset.py
- └── workflows/ # Workflow JSON files
- ├── generate_image.json
- └── generate_song.json
- ```
- ## Notes
- - The server binds to localhost by default. Do not expose it publicly without authentication or a reverse proxy.
- - Ensure your models exist in `<ComfyUI_dir>/models/checkpoints/`
- - Server uses **streamable-http** transport (HTTP-based, not WebSocket)
- - Workflows are auto-discovered - no code changes needed
- - Assets expire after 24 hours (configurable)
- - `view_image` only supports images (PNG, JPEG, WebP, GIF)
- - Asset identity uses `(filename, subfolder, type)` instead of URL for robustness
- - Full workflow history is stored for provenance and reproducibility
- - `regenerate` uses stored workflow data to recreate assets with parameter overrides
- - Session isolation: `list_assets` can filter by session for clean AI agent context
- ## Troubleshooting
- **Server won't start:**
- - Check ComfyUI is running on port 8188 (default)
- - Verify Python 3.8+ is installed (`python --version`)
- - Check all dependencies are installed: `pip install -r requirements.txt`
- - Check server logs for specific error messages
- **Client can't connect:**
- - Verify server shows "Server running at http://127.0.0.1:9000/mcp" in the console
- - Test server directly: `curl http://127.0.0.1:9000/mcp` (should return MCP response)
- - Check `.mcp.json` is in project root (or correct location for your client)
- - Try both `"type": "streamable-http"` and `"type": "http"` - both are supported
- - For Cursor-specific issues, see [docs/MCP_CONFIG_README.md](docs/MCP_CONFIG_README.md)
- **Tools not appearing:**
- - Check `workflows/` directory has JSON files with `PARAM_*` placeholders
- - Check server logs for workflow parsing errors
- - Verify ComfyUI has required custom nodes installed (if using custom workflows)
- - Restart the MCP server after adding new workflows
- **Asset not found errors:**
- - Assets expire after 24 hours by default (configurable via `COMFY_MCP_ASSET_TTL_HOURS`)
- - Assets are lost on server restart (ephemeral by design)
- - Use `get_asset_metadata` to verify asset exists before using `regenerate`
- - Check server logs to see if asset was registered successfully
- ## Known Limitations (v1.0)
- - **Ephemeral asset registry**: `asset_id` references are only valid while the MCP server is running (and until TTL expiry). After restart, previously-issued `asset_id`s can’t be resolved, and regenerate will fail for those assets.
- ## Contributing
- Issues and pull requests are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
- ## Acknowledgements
- - [@venetanji](https://github.com/venetanji) - streamable-http foundation & PARAM_* system
- ## Maintainer
- [@joenorton](https://github.com/joenorton)
- ## License
- Apache License 2.0
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.