Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/joenorton--comfyui-mcp-server/badge.svg)](/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

i

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)

  1. # ComfyUI MCP Server
  2. > Generate and refine AI images/audio/video through natural conversation
  3. A lightweight MCP (Model Context Protocol) server that lets AI agents generate and iteratively refine images, audio, and video using a local ComfyUI instance.
  4. You run the server, connect a client, and issue tool calls. Everything else is optional depth.
  5. ---
  6. ## Quick Start (2–3 minutes)
  7. This proves everything is working.
  8. ### 1) Clone and set up
  9. ```bash
  10. git clone https://github.com/joenorton/comfyui-mcp-server.git
  11. cd comfyui-mcp-server
  12. pip install -r requirements.txt
  13. ```
  14. ### 2) Start ComfyUI
  15. Make sure ComfyUI is installed and running locally.
  16. ```bash
  17. cd <ComfyUI_dir>
  18. python main.py --port 8188
  19. ```
  20. ### 3) Run the MCP server
  21. From the repository directory:
  22. ```bash
  23. python server.py
  24. ```
  25. The server listens at:
  26. ```
  27. http://127.0.0.1:9000/mcp
  28. ```
  29. ### 4) Verify it works (no AI client required)
  30. Run the included test client:
  31. ```bash
  32. # Use default prompt
  33. python test_client.py
  34. # Or provide your own prompt
  35. python test_client.py -p "a beautiful sunset over mountains"
  36. python test_client.py --prompt "a cat on a mat"
  37. ```
  38. `test_client.py` will:
  39. * connect to the MCP server
  40. * list available tools
  41. * fetch and display server defaults (width, height, steps, model, etc.)
  42. * run `generate_image` with your prompt (or a default)
  43. * automatically use server defaults for all other parameters
  44. * print the resulting asset information
  45. If this step succeeds, the system is working.
  46. **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.
  47. That’s it.
  48. ---
  49. ## Use with an AI Agent (Cursor / Claude / n8n)
  50. Once the server is running, you can connect it to an AI client.
  51. Create a project-scoped `.mcp.json` file:
  52. ```json
  53. {
  54. "mcpServers": {
  55. "comfyui-mcp-server": {
  56. "type": "streamable-http",
  57. "url": "http://127.0.0.1:9000/mcp"
  58. }
  59. }
  60. }
  61. ```
  62. **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.
  63. Restart your AI client. You can now call tools such as:
  64. * `generate_image`
  65. * `view_image`
  66. * `regenerate`
  67. * `get_job`
  68. * `list_assets`
  69. This is the primary intended usage mode.
  70. ---
  71. ## What You Can Do After It Works
  72. Once you’ve confirmed the server runs and a client can connect, the system supports:
  73. * Iterative refinement via `regenerate` (no re-prompting)
  74. * Explicit asset identity for reliable follow-ups
  75. * Job polling and cancellation for long-running generations
  76. * Optional image injection into the AI’s context (`view_image`)
  77. * Auto-discovered ComfyUI workflows with parameter exposure
  78. * Configurable defaults to avoid repeating common settings
  79. Everything below builds on the same basic loop you just tested.
  80. ## Migration Notes (Previous Versions)
  81. If you’ve used earlier versions of this project, a few things have changed.
  82. ### What’s the Same
  83. - You still run a local MCP server that delegates execution to ComfyUI
  84. - Workflows are still JSON files placed in the `workflows/` directory
  85. - Image generation behavior is unchanged at its core
  86. ### What’s New
  87. - **Streamable HTTP transport** replaces the older WebSocket-based approach
  88. - **Explicit job management** (`get_job`, `get_queue_status`, `cancel_job`)
  89. - **Asset identity** instead of ad-hoc URLs (stable across hostname changes)
  90. - **Iteration support** via `regenerate` (replay with parameter overrides)
  91. - **Optional visual feedback** for agents via `view_image`
  92. - **Configurable defaults** to avoid repeating common parameters
  93. ### What Changed Conceptually
  94. Earlier versions were a thin request/response bridge.
  95. The current version is built around **iteration** and **stateful control loops**.
  96. You can still generate an image with a single call, but you now have the option to:
  97. - refer back to specific outputs
  98. - refine results without re-specifying everything
  99. - poll and cancel long-running jobs
  100. - let AI agents inspect generated images directly
  101. ### Looking for the Old Behavior?
  102. If you want the minimal, single-shot behavior from earlier versions:
  103. - run `test_client.py` (this mirrors the original usage pattern)
  104. - call `generate_image` with just a prompt (server defaults handle the rest)
  105. - ignore the additional tools
  106. No migration is required unless you want the new capabilities.
  107. ## Available Tools
  108. ### Generation Tools
  109. - **`generate_image`**: Generate images (requires `prompt`)
  110. - **`generate_song`**: Generate audio (requires `tags` and `lyrics`)
  111. - **`regenerate`**: Regenerate an existing asset with optional parameter overrides (requires `asset_id`)
  112. ### Viewing Tools
  113. - **`view_image`**: View generated images inline (images only, not audio/video)
  114. ### Job Management Tools
  115. - **`get_queue_status`**: Check ComfyUI queue state (running/pending jobs) - provides async awareness
  116. - **`get_job`**: Poll job completion status by prompt_id - check if a job has finished
  117. - **`list_assets`**: Browse recently generated assets - enables AI memory and iteration
  118. - **`get_asset_metadata`**: Get full provenance and parameters for an asset - includes workflow history
  119. - **`cancel_job`**: Cancel a queued or running job
  120. ### Configuration Tools
  121. - **`list_models`**: List available ComfyUI models
  122. - **`get_defaults`**: Get current default values
  123. - **`set_defaults`**: Set default values (with optional persistence)
  124. ### Workflow Tools
  125. - **`list_workflows`**: List all available workflows
  126. - **`run_workflow`**: Run any workflow with custom parameters
  127. ### Publish Tools
  128. - **`get_publish_info`**: Show publish status (detected project root, publish dir, ComfyUI output root, and any missing setup)
  129. - **`set_comfyui_output_root`**: Set ComfyUI output directory (recommended for Comfy Desktop / nonstandard installs; persisted across restarts)
  130. - **`publish_asset`**: Publish a generated asset into the project's web directory with deterministic compression (default 600KB)
  131. **Publish Notes:**
  132. - **Session-scoped**: `asset_id`s are valid only for the current server session; restart invalidates them.
  133. - **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`.
  134. - **Two modes**: Demo (explicit filename) and Library (auto filename + manifest update). In library mode, `manifest_key` is required.
  135. - **Manifest**: Updated only when `manifest_key` is provided.
  136. - **Compression**: Deterministic ladder to meet size limits; fails with a clear error if it can't.
  137. **Quick Start:**
  138. Example agent conversation flow:
  139. **User:** "Generate a hero image for my website and publish it as hero.webp"
  140. **Agent:** *Checks publish configuration*
  141. - Calls `get_publish_info()` → sees status "ready"
  142. **Agent:** *Generates image*
  143. - Calls `generate_image(prompt="a hero image for a website")` → gets `asset_id`
  144. **Agent:** *Publishes asset*
  145. - Calls `publish_asset(asset_id="...", target_filename="hero.webp")` → success
  146. **User:** "Now generate a logo and add it to the manifest as 'site-logo'"
  147. **Agent:** *Generates and publishes with manifest*
  148. - Calls `generate_image(prompt="a modern logo")` → gets `asset_id`
  149. - Calls `publish_asset(asset_id="...", manifest_key="site-logo")` → auto-generates filename, updates manifest
  150. See [docs/HOW_TO_TEST_PUBLISH.md](docs/HOW_TO_TEST_PUBLISH.md) for detailed usage and testing instructions.
  151. ## Custom Workflows
  152. Add custom workflows by placing JSON files in the `workflows/` directory. Workflows are automatically discovered and exposed as MCP tools.
  153. ### Workflow Placeholders
  154. Use `PARAM_*` placeholders in workflow JSON to expose parameters:
  155. - `PARAM_PROMPT` → `prompt: str` (required)
  156. - `PARAM_INT_STEPS` → `steps: int` (optional)
  157. - `PARAM_FLOAT_CFG` → `cfg: float` (optional)
  158. **Example:**
  159. ```json
  160. {
  161. "3": {
  162. "inputs": {
  163. "text": "PARAM_PROMPT",
  164. "steps": "PARAM_INT_STEPS"
  165. }
  166. }
  167. }
  168. ```
  169. The tool name is derived from the filename (e.g., `my_workflow.json` → `my_workflow` tool).
  170. ---
  171. ## Configuration
  172. The server supports configurable defaults to avoid repeating common parameters. Defaults can be set via:
  173. - **Runtime defaults**: Use `set_defaults` tool (ephemeral, lost on restart)
  174. - **Config file**: `~/.config/comfy-mcp/config.json` (persistent)
  175. - **Environment variables**: `COMFY_MCP_DEFAULT_*` prefixed variables
  176. Defaults are resolved in priority order: per-call values → runtime defaults → config file → environment variables → hardcoded defaults.
  177. For complete configuration details, see [docs/REFERENCE.md](docs/REFERENCE.md#parameters).
  178. ---
  179. ## Detailed Reference
  180. Complete parameter lists, return schemas, configuration options, and advanced workflow metadata are documented in:
  181. - **[API Reference](docs/REFERENCE.md)** - Complete tool reference, parameters, return values, and configuration
  182. - **[Architecture](docs/ARCHITECTURE.md)** - Design decisions and system overview
  183. ## Project Structure
  184. ```
  185. comfyui-mcp-server/
  186. ├── server.py # Main entry point
  187. ├── comfyui_client.py # ComfyUI API client
  188. ├── asset_processor.py # Image processing utilities
  189. ├── test_client.py # Test client
  190. ├── managers/ # Core managers
  191. │ ├── workflow_manager.py
  192. │ ├── defaults_manager.py
  193. │ └── asset_registry.py
  194. ├── tools/ # MCP tool implementations
  195. │ ├── generation.py
  196. │ ├── asset.py
  197. │ ├── job.py # Job management tools
  198. │ ├── configuration.py
  199. │ └── workflow.py
  200. ├── models/ # Data models
  201. │ ├── workflow.py
  202. │ └── asset.py
  203. └── workflows/ # Workflow JSON files
  204. ├── generate_image.json
  205. └── generate_song.json
  206. ```
  207. ## Notes
  208. - The server binds to localhost by default. Do not expose it publicly without authentication or a reverse proxy.
  209. - Ensure your models exist in `<ComfyUI_dir>/models/checkpoints/`
  210. - Server uses **streamable-http** transport (HTTP-based, not WebSocket)
  211. - Workflows are auto-discovered - no code changes needed
  212. - Assets expire after 24 hours (configurable)
  213. - `view_image` only supports images (PNG, JPEG, WebP, GIF)
  214. - Asset identity uses `(filename, subfolder, type)` instead of URL for robustness
  215. - Full workflow history is stored for provenance and reproducibility
  216. - `regenerate` uses stored workflow data to recreate assets with parameter overrides
  217. - Session isolation: `list_assets` can filter by session for clean AI agent context
  218. ## Troubleshooting
  219. **Server won't start:**
  220. - Check ComfyUI is running on port 8188 (default)
  221. - Verify Python 3.8+ is installed (`python --version`)
  222. - Check all dependencies are installed: `pip install -r requirements.txt`
  223. - Check server logs for specific error messages
  224. **Client can't connect:**
  225. - Verify server shows "Server running at http://127.0.0.1:9000/mcp" in the console
  226. - Test server directly: `curl http://127.0.0.1:9000/mcp` (should return MCP response)
  227. - Check `.mcp.json` is in project root (or correct location for your client)
  228. - Try both `"type": "streamable-http"` and `"type": "http"` - both are supported
  229. - For Cursor-specific issues, see [docs/MCP_CONFIG_README.md](docs/MCP_CONFIG_README.md)
  230. **Tools not appearing:**
  231. - Check `workflows/` directory has JSON files with `PARAM_*` placeholders
  232. - Check server logs for workflow parsing errors
  233. - Verify ComfyUI has required custom nodes installed (if using custom workflows)
  234. - Restart the MCP server after adding new workflows
  235. **Asset not found errors:**
  236. - Assets expire after 24 hours by default (configurable via `COMFY_MCP_ASSET_TTL_HOURS`)
  237. - Assets are lost on server restart (ephemeral by design)
  238. - Use `get_asset_metadata` to verify asset exists before using `regenerate`
  239. - Check server logs to see if asset was registered successfully
  240. ## Known Limitations (v1.0)
  241. - **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.
  242. ## Contributing
  243. Issues and pull requests are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
  244. ## Acknowledgements
  245. - [@venetanji](https://github.com/venetanji) - streamable-http foundation & PARAM_* system
  246. ## Maintainer
  247. [@joenorton](https://github.com/joenorton)
  248. ## License
  249. Apache License 2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.