Skip to content
Back to search

comfyui-mcp

Local-first, agent-native control plane for ComfyUI — MCP server + sidebar agent that generates images, video & audio, authors and runs workflows, and edits your live graph in natural language on ANY LLM (Claude, ChatGPT, Gemini, offline Ollama, or any hosted model). 178 tools, 36 AI skills, 55 installer packs. Local, LAN, VPS, or Comfy Cloud.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/artokun/comfyui-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/artokun/comfyui-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/artokun--comfyui-mcp/badge.svg)](/listings/artokun--comfyui-mcp)

HTML

<a href="/listings/artokun--comfyui-mcp"><img src="/api/listings/artokun--comfyui-mcp/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.

**1. Install ComfyUI** (if you haven't already): [ComfyUI Desktop](https://www.comfy.org/download) or [from source](https://github.com/comfyanonymous/ComfyUI)

**2. Add the MCP server** to your Claude Code config (`~/.claude/settings.json`):

{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["-y", "comfyui-mcp"],
      "env": {
        "CIVITAI_API_TOKEN": ""
      }
    }
  }
}

**3. Start using it.** With ComfyUI running, ask Claude to generate an image:

> Generate an image of a sunset over mountains

Claude will find (or download) a checkpoint, build a workflow, execute it, and return the image.

> **Note**: This runs as a standalone MCP server, so there is no need to clone this repo. `npx` downloads and runs it.

Scope: local, remote, or Comfy Cloud

`comfyui-mcp` is **local-first**. A self-hosted ComfyUI on Mac/Linux/Windows is the primary target, and the same agent reaches remote installs (RunPod, VPS, LAN, reverse-proxied) from one config. Local-first, not local-only.

**More than a bridge.** Most ComfyUI MCP servers are thin connectors. They forward a prompt and hand back an image. `comfyui-mcp` is a full control plane. It authors and edits the graph node by node, runs and iterates on workflows, manages models and custom nodes, and ships model-specific expertise (samplers, CFG, resolutions, curated model URLs) so the agent gets it right without trial and error. If you want a minimal local relay, a lightweight server is fine. If you want an agent that *operates* ComfyUI, that's this project.

For Comfy Cloud users, Comfy-Org ships its own [agent tooling](https://docs.comfy.org/agent-tools): Comfy Cloud MCP (public beta, hosted on Comfy Cloud GPUs), the Comfy In-App Agent (private alpha, inside Comfy Cloud), and a first-party Comfy Local MCP (private test, not publicly available yet), all maintained by the Comfy team. If you don't have a GPU or you want zero setup, that's the better path; go use it.

Where this project differs is that it runs on **your** install and **your** choice of model, including a free local one via Ollama with no account and no network at all. `comfyui-mcp` *also* includes a community cloud mode (set `COMFYUI_API_KEY`, see [Deployment modes](#deployment-modes)) so a single MCP can target all three deployment shapes from one config.

**[Local vs. Comfy Cloud agent](https://comfyui-mcp.artokun.io/docs/local-vs-comfy-cloud)** is a side-by-side comparison, including when Comfy Cloud is the right answer. *(Statuses above are as of July 2026. Comfy-Org ships fast, so check their docs for the current state.)*

Remote / hosted connector (one command)

To use `comfyui-mcp` from Claude Desktop's Custom Connectors or any remote client, like Comfy's own `cloud.comfy.org/mcp` connector, run it as an authenticated, publicly reachable Streamable-HTTP server with one flag:

npx -y comfyui-mcp@latest --tunnel

This forces the HTTP transport, generates an auth token, opens a [cloudflared](https://github.com/cloudflare/cloudflared) quick tunnel, and prints a ready-to-paste `https://…/mcp` URL + token + Claude Desktop connector snippet. Auth accepts `Authorization: Bearer <token>` or `X-API-Key: <token>` (matching Comfy Cloud's convention). See the [Remote / hosted connector guide](https://comfyui-mcp.artokun.io/docs/remote-connector) for the full walkthrough and headless usage.

> Auth is opt-in. With no `COMFYUI_MCP_HTTP_TOKEN` set and no `--tunnel`, the > default stdio (and plain `--http` on loopback) behavior is unchanged. It stays open and > local. OAuth (Comfy's browser sign-in flow) is a planned follow-up.

---

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.

.claude-plugin/marketplace.json · Manifest · 16 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "comfyui-mcp",
  4. "description": "ComfyUI integration for Claude Code — workflow execution, visualization, model management, and skill generation",
  5. "owner": {
  6. "name": "artokun"
  7. },
  8. "plugins": [
  9. {
  10. "name": "comfy",
  11. "source": "./plugin",
  12. "description": "Claude Code plugin for ComfyUI — generate images, visualize workflows, manage models, and explore custom nodes",
  13. "version": "0.1.0"
  14. }
  15. ]
  16. }
README.md · README · 922 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # comfyui-mcp — drive ComfyUI with ANY LLM
  2. <p align="center">
  3. <a href="https://comfyui-mcp.artokun.io/docs">
  4. <img src="docs/images/demo-poster.jpg" width="760"
  5. alt="The Agent panel driving ComfyUI end to end. Click to watch the demo">
  6. </a>
  7. </p>
  8. <p align="center">
  9. <em>The Agent panel driving ComfyUI end to end. It reads what is installed locally,
  10. wires the graph, frees VRAM, and runs the render.<br>
  11. <a href="https://comfyui-mcp.artokun.io/docs">Watch the 76s demo &rarr;</a></em>
  12. </p>
  13. **The local-first, agent-native control plane for [ComfyUI](https://github.com/comfyanonymous/ComfyUI).** An MCP server plus a live sidebar agent that generates images, video and audio, authors and runs workflows, manages models and custom nodes, and **edits your live ComfyUI graph in natural language**. Bring whatever model you have: **Claude or ChatGPT on your subscription, Gemini on your Google login, a free local model via Ollama (fully offline), or any hosted model over one API key** (DeepSeek, GLM, MiMo, Kimi, GPT, Claude via OpenRouter). The tools and the panel are the same on every tier, and the built-in [LLM Arena](https://comfyui-mcp.artokun.io/docs/arena) scores each model on real ComfyUI tasks so you know what yours can do. One config targets local installs, LAN, VPS, or Comfy Cloud.
  14. [![npm version](https://img.shields.io/npm/v/comfyui-mcp)](https://www.npmjs.com/package/comfyui-mcp)
  15. [![Node.js](https://img.shields.io/badge/node-22.14%2B%20(22.x)%20or%2024%2B-brightgreen)](https://nodejs.org)
  16. [![License](https://img.shields.io/npm/l/comfyui-mcp)](./LICENSE)
  17. [![Documentation](https://img.shields.io/badge/docs-comfyui--mcp.artokun.io-2563EB?logo=readthedocs&logoColor=white)](https://comfyui-mcp.artokun.io/docs)
  18. [![comfyui-mcp MCP server](https://glama.ai/mcp/servers/artokun/comfyui-mcp/badges/card.svg)](https://glama.ai/mcp/servers/artokun/comfyui-mcp)
  19. [![comfyui-mcp MCP server](https://glama.ai/mcp/servers/artokun/comfyui-mcp/badges/score.svg)](https://glama.ai/mcp/servers/artokun/comfyui-mcp)
  20. [![Deploy on RunPod](https://img.shields.io/badge/Deploy_on-RunPod-673AB7?style=for-the-badge)](https://console.runpod.io/deploy?template=bnqtkvcer3&ref=dkx71w9b) [![Join the Discord](https://img.shields.io/badge/Discord-Join_%26_get_help-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/cW9arBhzCu) &nbsp;**One-click GPU pod.** A ready-to-run ComfyUI with this project + [Agent Panel](https://github.com/artokun/comfyui-mcp-panel) + ComfyUI-Manager v2 preinstalled, on your own GPU. No setup.
  21. Works on macOS, Linux, and Windows. Auto-detects your ComfyUI installation and port.
  22. **Stuck or have a question? [Join the Discord](https://discord.gg/cW9arBhzCu)** for help, model tips, and release announcements.
  23. **38 MCP tools** | **42 AI skills** (Flux · WAN · LTX 2.3 video · MiniMax H3 · Qwen · Z-Image · Ideogram 4 · ERNIE · ANIMA · model registry · Civitai · node authoring · launch/perf flags) | **56 installer packs** | **11 slash commands** | **4 autonomous agents** | **3 hooks**
  24. The plugin ships skills that grow with every release: model-specific generation guides with curated download URLs, workflow recipes, troubleshooting, and custom-node authoring. With them, Claude knows the right sampler, CFG, resolution, and model files for each architecture without trial and error.
  25. > ### Now available: the [ComfyUI Agent Panel](https://registry.comfy.org/nodes/comfyui-agent-panel) on ComfyUI-Manager & the Comfy Registry
  26. > An autonomous AI agent in your ComfyUI sidebar, running **on Claude, ChatGPT, Gemini, or ANY local/hosted LLM** (Ollama and every OpenAI-compatible endpoint). Subscriptions work with no API key; local models work with no account at all. Pick a provider and it drives your live graph: edits, spatial layout, one-shot workflow/pack loads, rewind/rollback, a pending-message tray, activity cards, multi-tab. It asks before spending paid API credits.
  27. > Search `comfyui-agent-panel` in ComfyUI-Manager to install. [Read more →](https://comfyui-mcp.artokun.io/docs/panel)
  28. **Full documentation: [comfyui-mcp.artokun.io/docs](https://comfyui-mcp.artokun.io/docs)**
  29. ---
  30. ## Quick Start
  31. **1. Install ComfyUI** (if you haven't already): [ComfyUI Desktop](https://www.comfy.org/download) or [from source](https://github.com/comfyanonymous/ComfyUI)
  32. **2. Add the MCP server** to your Claude Code config (`~/.claude/settings.json`):
  33. ```json
  34. {
  35. "mcpServers": {
  36. "comfyui": {
  37. "command": "npx",
  38. "args": ["-y", "comfyui-mcp"],
  39. "env": {
  40. "CIVITAI_API_TOKEN": ""
  41. }
  42. }
  43. }
  44. }
  45. ```
  46. **3. Start using it.** With ComfyUI running, ask Claude to generate an image:
  47. ```
  48. > Generate an image of a sunset over mountains
  49. ```
  50. Claude will find (or download) a checkpoint, build a workflow, execute it, and return the image.
  51. > **Note**: This runs as a standalone MCP server, so there is no need to clone this repo. `npx` downloads and runs it.
  52. ### Scope: local, remote, or Comfy Cloud
  53. `comfyui-mcp` is **local-first**. A self-hosted ComfyUI on Mac/Linux/Windows is the primary target, and the same agent reaches remote installs (RunPod, VPS, LAN, reverse-proxied) from one config. Local-first, not local-only.
  54. **More than a bridge.** Most ComfyUI MCP servers are thin connectors. They forward a prompt and hand back an image. `comfyui-mcp` is a full control plane. It authors and edits the graph node by node, runs and iterates on workflows, manages models and custom nodes, and ships model-specific expertise (samplers, CFG, resolutions, curated model URLs) so the agent gets it right without trial and error. If you want a minimal local relay, a lightweight server is fine. If you want an agent that *operates* ComfyUI, that's this project.
  55. For Comfy Cloud users, Comfy-Org ships its own [agent tooling](https://docs.comfy.org/agent-tools): Comfy Cloud MCP (public beta, hosted on Comfy Cloud GPUs), the Comfy In-App Agent (private alpha, inside Comfy Cloud), and a first-party Comfy Local MCP (private test, not publicly available yet), all maintained by the Comfy team. If you don't have a GPU or you want zero setup, that's the better path; go use it.
  56. Where this project differs is that it runs on **your** install and **your** choice of model, including a free local one via Ollama with no account and no network at all. `comfyui-mcp` *also* includes a community cloud mode (set `COMFYUI_API_KEY`, see [Deployment modes](#deployment-modes)) so a single MCP can target all three deployment shapes from one config.
  57. **[Local vs. Comfy Cloud agent](https://comfyui-mcp.artokun.io/docs/local-vs-comfy-cloud)** is a side-by-side comparison, including when Comfy Cloud is the right answer. *(Statuses above are as of July 2026. Comfy-Org ships fast, so check their docs for the current state.)*
  58. ### Remote / hosted connector (one command)
  59. To use `comfyui-mcp` from Claude Desktop's Custom Connectors or any remote
  60. client, like Comfy's own `cloud.comfy.org/mcp` connector, run it as an
  61. authenticated, publicly reachable Streamable-HTTP server with one flag:
  62. ```bash
  63. npx -y comfyui-mcp@latest --tunnel
  64. ```
  65. This forces the HTTP transport, generates an auth token, opens a
  66. [cloudflared](https://github.com/cloudflare/cloudflared) quick tunnel, and prints
  67. a ready-to-paste `https://…/mcp` URL + token + Claude Desktop connector snippet.
  68. Auth accepts `Authorization: Bearer <token>` or `X-API-Key: <token>` (matching
  69. Comfy Cloud's convention). See the
  70. [Remote / hosted connector guide](https://comfyui-mcp.artokun.io/docs/remote-connector)
  71. for the full walkthrough and headless usage.
  72. > Auth is opt-in. With no `COMFYUI_MCP_HTTP_TOKEN` set and no `--tunnel`, the
  73. > default stdio (and plain `--http` on loopback) behavior is unchanged. It stays open and
  74. > local. OAuth (Comfy's browser sign-in flow) is a planned follow-up.
  75. ---
  76. ## Claude Code Plugin
  77. This package also ships as a Claude Code plugin that adds slash commands, skills, agents, and hooks on top of the MCP tools.
  78. ### Install as a plugin
  79. ```bash
  80. # In Claude Code
  81. /plugin marketplace add artokun/comfyui-mcp
  82. /plugin install comfy
  83. ```
  84. ### Slash commands
  85. | Command | Description |
  86. |---------|-------------|
  87. | `/comfy:gen <prompt>` | Generate an image from a text description — auto-selects checkpoint, builds workflow, returns image |
  88. | `/comfy:viz <workflow>` | Visualize a workflow as a Mermaid diagram with nodes grouped by category |
  89. | `/comfy:node-skill <pack>` | Generate a Claude skill for a custom node pack from Registry ID or GitHub URL |
  90. | `/comfy:debug [prompt_id]` | Diagnose why a workflow failed — reads history, logs, traces root cause, suggests fixes |
  91. | `/comfy:batch <prompt, params>` | Parameter sweep generation across cfg, sampler, steps, seed, etc. |
  92. | `/comfy:convert <file>` | Convert between UI format and API format workflows |
  93. | `/comfy:install <pack>` | Install a custom node pack — git clone, pip install, optional restart |
  94. | `/comfy:gallery [filter]` | Browse generated outputs with metadata — filter by date, count, or filename |
  95. | `/comfy:compare <a vs b>` | Diff two workflows side by side — shows added/removed nodes and changed parameters |
  96. | `/comfy:recipe <name> <prompt>` | Multi-step recipes: `portrait`, `hires-fix`, `style-transfer`, `product-shot` |
  97. ### Built-in skills
  98. 42 skills total: model-family guides (Flux, WAN, LTX 2.3, MiniMax H3, Qwen, Z-Image, Ideogram 4, ERNIE, ANIMA + anime / WAN / Z-Image LoRA training), the **model-registry** (curated download URLs), the **civitai** pairing skill, node authoring, the **launch/performance-flags** matrix, and the core four below. Full list on the [plugin docs page](https://comfyui-mcp.artokun.io/docs/plugin).
  99. > **Installer packs.** [`packs/`](packs/) bundles 13 one-command ComfyUI setups: ANIMA, Ideogram 4, LTX-2.3, ERNIE, WAN (animate / longer-videos / transparent), Qwen (image / image-edit), Z-Image (turbo / base / xy-plot) and artokun-flow (WAN Animate: replace / animate). Each is a manifest of custom nodes + model URLs + workflow that drives both `apply_manifest` and generated `install-windows.bat` / `install-runpod.sh`, with CI that validates every model link + payload size. See [`packs/README.md`](packs/README.md).
  100. | Skill | Description |
  101. |-------|-------------|
  102. | **comfyui-core** | Workflow format, node types, data flow patterns, pipeline architecture, MCP tool usage guide |
  103. | **prompt-engineering** | CLIP weight syntax `(word:1.3)`, BREAK tokens, embeddings, model-specific prompting for SD1.5/SDXL/Flux/SD3 |
  104. | **troubleshooting** | Common error catalog — OOM, dtype mismatches, missing nodes, NaN tensors, black images, CUDA errors, with VRAM estimates per model |
  105. | **model-compatibility** | Compatibility matrix — loaders, resolutions, CFG, samplers, ControlNets, LoRAs, and VAEs per model family (SD1.5/SDXL/Turbo/Lightning/Flux/SD3/LTXV) |
  106. ### Agents
  107. | Agent | Model | Description |
  108. |-------|-------|-------------|
  109. | **comfy-explorer** | Sonnet | Researches custom node packs — reads docs, queries `/object_info`, generates skill files |
  110. | **comfy-debugger** | Sonnet | Autonomously diagnoses workflow failures — gathers logs + history, identifies failing node, checks models + custom nodes, proposes and optionally applies fixes |
  111. | **comfy-optimizer** | Sonnet | Analyzes workflows for performance — detects redundant nodes, VRAM waste, wrong CFG/steps for model family, precision issues, suggests optimizations |
  112. | **comfy-researcher** | Sonnet | Discovers and ranks ComfyUI custom node packs for a stated image-generation problem |
  113. ### Hooks
  114. | Event | Trigger | Action |
  115. |-------|---------|--------|
  116. | PreToolUse | `enqueue_workflow` | **VRAM watchdog** — checks GPU memory via `/system_stats` and warns if < 1GB free before execution |
  117. | PreToolUse | `restart_comfyui` (actions `stop`/`restart`) | **Save warning** — prompts user to save unsaved workflow changes before stopping ComfyUI |
  118. | PostToolUse | Any comfyui tool | **Job completion notify** — checks for completed jobs and injects completion summaries into the conversation |
  119. ### Background Scripts
  120. | Script | Description |
  121. |--------|-------------|
  122. | `monitor-progress.mjs` | **Progress monitor** — connects to ComfyUI's WebSocket for real-time step progress (e.g., `step 5/14 (36%)`). Run as a background Bash task after enqueuing workflows. Reports completion with output filenames, errors with node details. Replaces polling `queue` (action:"status") in a loop. |
  123. ---
  124. ## Panel agent (Claude · ChatGPT · Gemini · any local/hosted LLM)
  125. Beyond the headless MCP server, this package ships the panel orchestrator that
  126. powers the [ComfyUI Agent Panel](https://github.com/artokun/comfyui-mcp-panel),
  127. an autonomous agent embedded in ComfyUI's sidebar that drives the live canvas. It
  128. runs in the background on your own subscription (Claude *or* ChatGPT), started
  129. on demand by the panel's **Connect** button:
  130. ```bash
  131. npx -y comfyui-mcp@latest connect
  132. ```
  133. ### Drive a REMOTE ComfyUI from your own machine (`connect`)
  134. When ComfyUI runs somewhere with no Node or agent (a RunPod pod, a cloud box) you
  135. can still run the agent on your machine and drive that remote ComfyUI. There is no
  136. agent login on the box and nothing to install or configure remotely:
  137. ```bash
  138. npx -y comfyui-mcp@latest connect https://abcd1234-3000.proxy.runpod.net
  139. ```
  140. This is sugar for `--panel-orchestrator` with `COMFYUI_URL` set from the URL. The
  141. orchestrator runs locally on your Claude/ChatGPT login and reaches the remote
  142. ComfyUI over its public proxy URL. For a remote HTTPS pod, `connect`
  143. opens a token-gated `wss://` tunnel (via Cloudflare) to
  144. the local agent bridge and hands the pod's panel that URL, so the pod's HTTPS page
  145. reaches your machine with no browser prompt, in any browser. A secure page
  146. can't open a plain `ws://` socket to your box because of mixed-content and Private Network
  147. Access rules. A local ComfyUI uses the plain `ws://127.0.0.1:9199` loopback bridge.
  148. Add `--insecure-bridge` to force that loopback for a remote pod, then arrange
  149. your own path to it, e.g. an SSH port-forward. Either way the panel JS runs in
  150. your local browser, and the agent and your login run only on your
  151. machine, so nothing is installed remotely.
  152. To finish, with `connect` still running on your machine, open the remote ComfyUI in
  153. your browser and click **Connect** in the Agent panel. The panel is a pure-frontend
  154. extension. It links to the bridge your `connect` process is already serving, rather
  155. than asking the ComfyUI host to spawn an orchestrator it cannot run.
  156. **Multi-provider, full parity.** The orchestrator depends on a provider-neutral
  157. `AgentBackend` port (dependency injection), with two adapters:
  158. - `ClaudeBackend` wraps the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)
  159. (`@anthropic-ai/claude-agent-sdk`), a persistent streaming session over the
  160. claude.ai subscription (OAuth, no key).
  161. - `CodexBackend` wraps OpenAI Codex over the `codex app-server` JSON-RPC
  162. protocol (`@openai/codex`), on the ChatGPT subscription (`codex login`, no key).
  163. Further adapters follow the same port: Gemini CLI (ACP), Antigravity
  164. (`agy`, the Google AI Pro/Ultra subscription path; install from
  165. [antigravity.google](https://antigravity.google) and run `agy` once to sign
  166. in), Grok, Kimi, GLM, Ollama/LM Studio/llama.cpp (local), OpenRouter, and
  167. any OpenAI-compatible endpoint. See
  168. [docs/backends](https://comfyui-mcp.artokun.io/docs/backends) for the full
  169. matrix.
  170. Both are optional dependencies, and the panel picks a provider, not a port.
  171. Each backend runs its own orchestrator on its own loopback bridge port. A
  172. capability matrix tells the panel which features each backend supports (e.g. conversation-rollback is
  173. Claude-only today, since the Codex app-server resumes whole threads only).
  174. **The live-canvas tools and model knowledge are identical across providers.** The
  175. `panel_*` tool definitions live in one shared list, registered onto both the
  176. in-process Claude SDK MCP server *and* a `@modelcontextprotocol/sdk` server over a
  177. loopback streamable-HTTP MCP that the orchestrator hosts for Codex (which can
  178. only host config-declared MCP servers). The headless `comfyui` MCP is likewise
  179. injected into both, in-process for Claude and declared via `codex app-server -c
  180. mcp_servers` for ChatGPT, so generation, models, and workflow tools are the same
  181. everywhere.
  182. New tools that give every backend the same expertise and a cost guardrail:
  183. | Tool | Description |
  184. |------|-------------|
  185. | `list_packs` (`action: "skill_list"` / `"skill_read"`) | Discover and read bundled model-family + workflow skills — the knowledge Claude loads natively, exposed to any MCP client (e.g. the Codex backend) |
  186. | `list_packs` (`action: "list"` / `"read_workflow"`) | List one-command installer packs (custom nodes + weights + ready workflow; all local-GPU / free) and read a pack's graph |
  187. | `list_packs` (`action: "list_templates"`) | List the connected ComfyUI's custom-node-contributed workflow templates |
  188. | `list_packs` (`action: "check_runtime"`) | Classify a workflow as **local** (your GPU, free) or **api** / **mixed** / **unknown** (hosted API nodes = paid credits) so the agent asks before spending paid API credits |
  189. | `list_packs` (`action: "extract_deps"` / `"install_deps"`) | Work out which custom node packs a workflow needs, and install the missing ones through ComfyUI-Manager |
  190. | `panel_load_workflow` | (panel tool) Load a full workflow onto the live canvas in one shot — by bundled `pack` name (read server-side, never shuttled through chat) or by graph JSON |
  191. | `panel_strip_workflow` / `panel_slice_workflow` | (panel tools) De-virtualize a tangled graph (Get/Set buses, Reroutes, subgraphs, bypass → real connections) or carve one rgthree-toggled pipeline out of a monolith — by `pack`, server-side `path`, or inline graph; for understanding/rebuilding expert workflows without hand-tracing |
  192. ---
  193. ## MCP Tools
  194. 38 tools across workflow execution, generation, iteration, composition, models, and more:
  195. ### Image Generation (high-level)
  196. | Tool | Description |
  197. |------|-------------|
  198. | `generate_image` `action: "image"` | Generate from a text prompt — builds a txt2img workflow, fills unspecified params from your defaults, auto-selects a checkpoint |
  199. | `generate_image` `action: "controlnet"` | Generate conditioned by a ControlNet image (pose/depth/canny/normal) + prompt |
  200. | `generate_image` `action: "ip_adapter"` | Generate guided by a reference image's style/subject via IP-Adapter (needs ComfyUI_IPAdapter_plus) |
  201. | `generate_image` `action: "video"` / `"3d"` | Generate a short video clip (LTX-2.3, local GPU) or a 3D model (hosted partner API nodes) from the same one-line entry point |
  202. | `generate_image` `action: "upscale"` | Post-process an uploaded or staged image with ESRGAN super-resolution |
  203. | generate_image (action:"remove_background") | Post-process an uploaded or staged image into a transparent BiRefNet cutout |
  204. ### Audio Generation (high-level)
  205. | Tool | Description |
  206. |------|-------------|
  207. | `generate_image` `action: "audio"` | Generate audio from a text prompt — supports ACE Step 1.5 (music with lyrics/structure) and Stable Audio 3 (music, instruments, SFX); auto-selects local models |
  208. ### Assets & Iteration
  209. | Tool | Description |
  210. |------|-------------|
  211. | `get_image (action:"view")` | Return a generated asset's bytes as an inline image so the agent can see the result |
  212. | `get_image (action:"analyze_color")` | Palette / contrast / color statistics for a generated image (dominant colors, average + luminance stats, contrast checks) so the agent can reason about color without a vision round-trip |
  213. | generate_image (action:"regenerate") | Re-run the workflow that produced an `asset_id`, with optional parameter overrides |
  214. | `get_image (action:"list_assets")` | Browse recently generated assets (newest-first) by `asset_id` |
  215. | `get_image (action:"asset_metadata")` | Full provenance for an asset, including the originating workflow |
  216. ### Defaults
  217. | Tool | Description |
  218. |------|-------------|
  219. | `get_defaults` `action:"get"` | Show merged generation defaults with per-source attribution |
  220. | `get_defaults` `action:"set"` | Update runtime defaults; `persist: true` writes the config file |
  221. | `get_defaults` `action:"get_ui"` / `action:"set_ui"` | Read/write ComfyUI's OWN frontend UI settings (the `Comfy.*` ids) — a separate store from the generation defaults above |
  222. ### Workflow Execution
  223. | Tool | Description |
  224. |------|-------------|
  225. | `enqueue_workflow` `action: "enqueue"` | Submit a workflow (API format JSON) — returns `prompt_id` immediately, non-blocking |
  226. | `enqueue_workflow` `action: "rerun"` / `"run_url"` / `"template_schema"` | Re-run a past generation, or read/run a shared workflow from a URL, or inspect a bundled template's overridable slots |
  227. | enqueue_workflow (action:"run_template") | One-shot: resolve a bundled pack's expert graph, apply `<nodeId>.<widget>` overrides, and enqueue it |
  228. | `queue` | One action-parameterized tool for the execution queue: `list` (running + pending), `status` (one job by prompt ID), `get_workflow` (a pending job's full payload), `move`/`edit` (requeue a pending job front/back, patched or replaced, with a new prompt ID), `cancel` (interrupt the running job — escalates interrupt → verify → `/free`, reports WEDGED if it won't die; `clear_pending: true` also drops all pending), `cancel_queued`, `clear` |
  229. | `get_system_stats` | Get system info — GPU, VRAM, Python version, OS |
  230. ### Workflow Visualization
  231. | Tool | Description |
  232. |------|-------------|
  233. | `visualize_workflow` | One action-parameterized tool for rendering and converting a workflow you pass in: `render` (Mermaid flowchart, nodes grouped by category), `render_hierarchical` (the same graph sectioned — overview, one section in detail, a listing, or an AI-oriented summary), `mermaid` (a Mermaid diagram back to executable workflow JSON), `to_dsl`/`from_dsl` (the compact, losslessly round-tripping authoring DSL) |
  234. ### Workflow Composition
  235. | Tool | Description |
  236. |------|-------------|
  237. | `create_workflow` | One action-parameterized tool for authoring: `create` (from templates: `txt2img`, `img2img`, `upscale`, `inpaint`, `controlnet`, `ip_adapter`, `ace_step_15`, `stable_audio_3`), `modify` (operations: `set_input`, `add_node`, `remove_node`, `connect`, `insert_between`), `validate` (dry-run — missing nodes, broken connections, invalid output indices, missing model files), `node_info` (query available node types from ComfyUI's `/object_info` endpoint) |
  238. ### Workflow Library
  239. | Tool | Description |
  240. |------|-------------|
  241. | `get_workflow` | One action-parameterized tool for READING a saved workflow file: `list` (the user library, subfolders included), `get` (one workflow's JSON by filename), `analyze` (a structured summary instead of raw JSON), `query` (filter/traverse/aggregate a big graph without dumping it), `strip` (**de-virtualize** any workflow from an absolute path, library filename, or inline graph — resolve GetNode/SetNode buses, Reroutes, subgraph defs, and bypassed nodes into real connections and return the flat graph; reads ANY path server-side, so it loads ad-hoc/expert workflows the cached library can't), `slice` (**un-chunk** a toggle-template monolith — one rgthree Fast-Groups-Bypass-toggled pipeline out into a standalone activated graph; pair with `strip` to then flatten the buses), `from_image` (the workflow ComfyUI embedded in a PNG), `prompt_director` (Prompt Director's sanitized runtime state) |
  242. | `save_workflow` | One action-parameterized tool for WRITING to the library: `save` (store a workflow — overwrites a same-filename file), `lock` (record a provenance lock: SHA-256 per model, git commit per node pack), `verify_lock` (report drift against that lock) |
  243. ### Image Management
  244. | Tool | Description |
  245. |------|-------------|
  246. | `upload_image` | Copy a local image into ComfyUI's `input/` directory for img2img, inpaint, or ControlNet |
  247. | `get_image (action:"list_outputs")` | Browse recently generated images **and videos** from the output directory, sorted newest-first — recurses into subfolders (e.g. SaveVideo's `output/video/…`) and returns each result's `subfolder` |
  248. ### Model Management
  249. | Tool | Description |
  250. |------|-------------|
  251. | `download_model` | Find and fetch model weights, and track the transfers. `action`: `download` (from a URL, into the correct ComfyUI subdirectory), `status`, `cancel`, `search` (HuggingFace), `search_civitai`, `search_creators`, `download_civitai`, `resolve_missing` |
  252. | `list_local_models` | What is installed, and where ComfyUI looks. `action`: `list` (installed models by type: checkpoints, loras, vae, upscale_models, controlnet, embeddings, clip, unet, diffusion_models, text_encoders), `remove` (**deletes a model file**), `embeddings`, `list_paths`, `add_path`, `remove_path` (the last three view/edit the extra search-path YAML) |
  253. ### Memory Management
  254. | Tool | Description |
  255. |------|-------------|
  256. | `clear_vram` | Free GPU VRAM by unloading cached models — calls ComfyUI's `/free` endpoint, reports before/after stats |
  257. ### Registry & Discovery
  258. | Tool | Description |
  259. |------|-------------|
  260. | `search_custom_nodes` | Search the ComfyUI Registry for node packs by keyword (`action: "search"`), or get one pack's full details (`action: "details"`) |
  261. | `list_packs` (`action: "generate_skill"`) | Generate a Claude skill `.md` file from a Registry ID or GitHub URL |
  262. | `comfy_cli` | Search actual loaded node classes through official `comfy nodes search` (action:"search_nodes") |
  263. ### Official comfy-cli
  264. Install [comfy-cli](https://docs.comfy.org/comfy-cli/getting-started#install-cli) 1.11.1 or newer to enable the official JSON-backed tools. The MCP resolves `comfy` from `COMFY_CLI_PATH`, `PATH`, or the selected workspace's `.venv`/`venv`. Local custom-node operations prefer `comfy node` when a supported CLI is available and otherwise fall back to Manager HTTP; remote targets keep using Manager HTTP.
  265. | Tool | Description |
  266. |------|-------------|
  267. | `comfy_cli` | One action-parameterized tool for the whole official CLI: `status`, `server_start`/`server_stop`/`server_restart`, `jobs_list`/`jobs_status`/`jobs_wait`/`jobs_watch`/`jobs_cancel`, `search_nodes`, `workflow_validate`/`workflow_run`, `transfer_upload`/`transfer_download`, `models_*` (list/search/show/download/remove), `skills_*` (list/show/validate/install/status/uninstall) |
  268. ### Diagnostics
  269. | Tool | Description |
  270. |------|-------------|
  271. | `get_system_stats (action:"logs")` | Get ComfyUI server logs with optional keyword filter (e.g., `error`, `warning`, a node name) |
  272. | `kitchen` | See what comfy-kitchen can do on this GPU (`status`), find where a graph leaves it on the table (`assess`), and apply the faster path (`apply`) — a failed probe is unknown, never a no |
  273. | `get_history` `action: "list"` | Get execution history with full error details, Python tracebacks, timing, and cached node info |
  274. | `get_history` `action: "diagnose"` | Explain a FAILED run in one call — the failed node and traceback PLUS the missing models (file + widget) and missing node types |
  275. ### Process Control
  276. | Tool | Description |
  277. |------|-------------|
  278. | `restart_comfyui` `action:"restart"` | Stop and restart ComfyUI, preserving all launch arguments |
  279. | `restart_comfyui` `action:"stop"` | Stop the running ComfyUI process (saves PID and launch args for restart; on Windows, `action:"start"` cannot bring it back) |
  280. | `restart_comfyui` `action:"start"` | Start ComfyUI using info saved from a previous stop (macOS/Linux; refused on Windows) |
  281. | `restart_comfyui` `action:"status"` | Read-only: what start/stop/restart would do now, and whether a stop could be undone by this tool. Call it before `stop` |
  282. ### Generation Tracker
  283. | Tool | Description |
  284. |------|-------------|
  285. | `get_history` `action: "suggest"` | Suggest proven sampler/scheduler/steps/CFG settings from local generation history — query by model family, LoRA hash, or text search |
  286. | `get_history` `action: "stats"` | Show local generation tracking statistics — total runs, unique combos, breakdown by model family |
  287. Every `enqueue_workflow` call logs settings to a local SQLite database (`generations.db`). Repeated settings combos get a `reuse_count` bump instead of a duplicate row, so the count works as a popularity signal. The tracker identifies models and LoRAs by content hash (AutoV2 / SHA256), not filename, so renamed files still group together.
  288. ```bash
  289. # View local stats from the CLI
  290. npm run generations:stats
  291. ```
  292. ---
  293. ## Examples
  294. ### Generate an image
  295. ```
  296. > /comfy:gen a cyberpunk city at night with neon lights
  297. ```
  298. Claude will:
  299. 1. Check installed checkpoints (download one if needed)
  300. 2. Build a txt2img workflow with your prompt
  301. 3. Execute it on ComfyUI
  302. 4. Return the generated image
  303. ### Visualize a workflow
  304. ```
  305. > /comfy:viz ~/workflows/my-workflow.json
  306. ```
  307. Produces a Mermaid diagram with nodes grouped by category:
  308. ```mermaid
  309. flowchart LR
  310. subgraph Loaders
  311. 1["CheckpointLoaderSimple"]
  312. end
  313. subgraph Conditioning
  314. 2(["Positive Prompt"])
  315. 3(["Negative Prompt"])
  316. end
  317. subgraph Sampling
  318. 5{{"KSampler<br/>steps:20 cfg:8"}}
  319. end
  320. 1 -->|MODEL| 5
  321. 2 -->|CONDITIONING| 5
  322. 3 -->|CONDITIONING| 5
  323. ```
  324. ### Debug a failed workflow
  325. ```
  326. > /comfy:debug
  327. ```
  328. Reads the last execution history and logs, identifies the failing node, checks for missing models or node packs, and suggests a fix.
  329. ```
  330. > /comfy:debug abc123-def456
  331. ```
  332. Diagnose a specific execution by prompt ID.
  333. ### Parameter sweep
  334. ```
  335. > /comfy:batch a cat in a field, cfg:5-10:2, sampler:euler,dpmpp_2m
  336. ```
  337. Generates a grid of images across all parameter combinations and presents a summary table with results.
  338. Supported sweep parameters: `cfg`, `steps`, `sampler`, `scheduler`, `seed`, `denoise`, `width`, `height`.
  339. ### Multi-step recipes
  340. ```
  341. > /comfy:recipe hires-fix a dramatic fantasy landscape with castles
  342. ```
  343. Runs two passes: txt2img at 512x768, then an img2img upscale to 1024x1536 that adds detail.
  344. Available recipes:
  345. | Recipe | Description |
  346. |--------|-------------|
  347. | `portrait` | Generate at 1024x1024, then 2x upscale to 2048x2048 |
  348. | `hires-fix` | Low-res generation → img2img upscale with denoise 0.4-0.5 |
  349. | `style-transfer` | Apply a style prompt to an existing image via img2img |
  350. | `product-shot` | Product image with clean white background |
  351. ### Convert workflow format
  352. ```
  353. > /comfy:convert ~/workflows/my-ui-workflow.json
  354. ```
  355. Converts between ComfyUI's UI format (nodes + links arrays) and API format (node IDs → {class_type, inputs}).
  356. ### Install a custom node pack
  357. ```
  358. > /comfy:install comfyui-impact-pack
  359. ```
  360. Searches the registry, shows details, clones the repo to `custom_nodes/`, installs dependencies, and offers to restart ComfyUI.
  361. ### Browse output gallery
  362. ```
  363. > /comfy:gallery last 5
  364. > /comfy:gallery today
  365. ```
  366. Lists recent outputs with their embedded metadata: checkpoint, prompt, seed, steps, CFG, and sampler for each image.
  367. ### Compare workflows
  368. ```
  369. > /comfy:compare workflow-a.json vs workflow-b.json
  370. ```
  371. Shows added/removed nodes, changed parameters (old → new values), and optional Mermaid diagrams for visual comparison.
  372. ### Validate before running
  373. ```
  374. > Validate this workflow before I run it
  375. ```
  376. Checks for missing node types, broken connections, invalid output indices, and missing model files without executing the workflow.
  377. ### Manage models
  378. ```
  379. > What checkpoints do I have installed?
  380. > Search HuggingFace for SDXL turbo models
  381. > Download this model to my checkpoints folder
  382. ```
  383. ### Manage VRAM
  384. ```
  385. > Free my VRAM
  386. > What embeddings do I have?
  387. ```
  388. ### Extract workflow from an image
  389. ```
  390. > Extract the workflow from this image: ~/outputs/ComfyUI_00042_.png
  391. ```
  392. Reads the PNG metadata chunks to recover the exact workflow and prompt used to generate the image.
  393. ### Explore custom nodes
  394. ```
  395. > /comfy:node-skill comfyui-impact-pack
  396. ```
  397. Generates a skill file documenting every node, its inputs/outputs, and usage patterns.
  398. ### Process control
  399. ```
  400. > Restart ComfyUI
  401. > Stop ComfyUI
  402. > Start ComfyUI back up
  403. ```
  404. ---
  405. ## Configuration
  406. The server auto-detects your ComfyUI installation and port. Override with environment variables if needed.
  407. Where to put keys and overrides:
  408. - **Panel users.** Use the **API Keys** card (▾ menu next to "connected"). Keys are stored in `~/.comfyui-mcp/panel-secrets.json` and take effect without a restart.
  409. - **MCP-only setups** (Claude Desktop, Claude Code, etc.). Use the `env` block of your MCP client config, as shown in the setup examples above.
  410. - Real environment variables always take precedence over stored keys. For development, the server also loads `~/.comfyui-mcp/.env` as an override file; regular installs shouldn't need it.
  411. ### Deployment modes
  412. `comfyui-mcp` operates in one of three modes, auto-selected from the environment:
  413. | Mode | Trigger | Local FS / process tools? |
  414. |------|---------|----------------------------|
  415. | **Local** | default | yes |
  416. | **Remote** | `--comfyui-url` / `COMFYUI_URL` points at a non-loopback host, or `--force-remote` is set | no — server skips `COMFYUI_PATH` auto-detection so stale local installs can't silently absorb uploads |
  417. | **Cloud** | `COMFYUI_API_KEY` is set (targets [Comfy Cloud](https://cloud.comfy.org)) | no — HTTP primitives route via `cloud.comfy.org` over `X-API-Key`; WebSocket and local-only tools throw `CLOUD_UNSUPPORTED` |
  418. Some setups (e.g. [dstack](https://dstack.ai) driving ComfyUI on RunPod) port-forward
  419. a remote ComfyUI back to `localhost:8188`, so the loopback check above reports a
  420. local install that isn't one. Pass `--force-remote` (or set
  421. `COMFYUI_MCP_FORCE_REMOTE=1`) alongside `--comfyui-url`/`COMFYUI_URL` to force
  422. remote mode regardless of hostname:
  423. ```bash
  424. npx -y comfyui-mcp@latest --comfyui-url http://localhost:8188 --force-remote
  425. ```
  426. | Variable | Default | Description |
  427. |----------|---------|-------------|
  428. | `COMFYUI_URL` | | Full ComfyUI URL, e.g. `https://comfy.example.com:8443` — overrides `COMFYUI_HOST`/`PORT`/`SSL` and skips auto-detection. A **path prefix is preserved** (e.g. `https://host/comfyapi`) for reverse-proxied instances. Non-loopback hosts opt into **remote mode**. |
  429. | `COMFYUI_MCP_FORCE_REMOTE` | | Set to `1`/`true` (or pass `--force-remote`) to force **remote mode** even when `COMFYUI_URL`/`--comfyui-url` resolves to a loopback host — for port-forwarded remote installs (e.g. dstack/RunPod) that are reachable at `localhost`. No effect without a `COMFYUI_URL`/`--comfyui-url`. |
  430. | `COMFYUI_HOST` | `127.0.0.1` | ComfyUI server address |
  431. | `COMFYUI_PORT` | *(auto-detect)* | ComfyUI server port (tries 8188, then 8000) |
  432. | `COMFYUI_PATH` | *(auto-detect)* | Path to the ComfyUI data/base directory used for models, input/output and user state. In a conventional install this is also the checkout. Auto-detection suppressed in remote/cloud modes. |
  433. | `COMFYUI_CODE_PATH` | `COMFYUI_PATH` | Optional path to the ComfyUI checkout (`main.py`, `.venv`, core git) when code and data live under different roots. Pip, venv, and core updates use this checkout (core updates prefer the checkout observed from the connected local server and use this as their fallback). Pack reads/writes — `custom_nodes`, comfy-cli `--workspace`, `apply_manifest` clone/checkout, workflow-lock pack commits — stay on the live `--base-directory` / `COMFYUI_PATH` data root (#1770). |
  434. | `COMFY_CLI_PATH` | *(auto-detect)* | Path to the official `comfy` executable (comfy-cli >=1.11.1). Resolution also checks `PATH` and the selected workspace's `.venv`/`venv`. |
  435. | `COMFYUI_PYTHON` | `python` | Python interpreter used by legacy git-clone dependency fallbacks. Point it at your ComfyUI venv's Python when needed. |
  436. | `COMFYUI_MCP_BRIDGE_HOST` | `127.0.0.1` | Panel-bridge bind host. Set `0.0.0.0` (or a LAN IP) to run the orchestrator on a 24/7 server and connect panels from other machines — **requires a token** (below); the orchestrator prints a ready-to-paste `ws://…/?token=…` Bridge URL. |
  437. | `COMFYUI_MCP_BRIDGE_TOKEN` | *(generated when needed)* | Shared secret gating every bridge connection (checked constant-time on the WS upgrade). Mandatory for a non-loopback `COMFYUI_MCP_BRIDGE_HOST`; pin it so the Bridge URL survives restarts. Never logged beyond the startup banner. |
  438. | `COMFYUI_MCP_DATA_DIR` | `~/.comfyui-mcp` | Base dir for per-instance data (the `generations.db` behind `get_history` `action: "suggest"`) when there's no local `COMFYUI_PATH` (remote/cloud/undetected). Scoped per target under `instances/<host_port>/`. |
  439. | `COMFYUI_API_KEY` | | Comfy Cloud API key. When set, **cloud mode** is active and the server talks to `cloud.comfy.org`. Never logged. |
  440. | `COMFYUI_CLOUD_URL` | `https://cloud.comfy.org` | Override the Comfy Cloud endpoint (testing/staging). |
  441. | `COMFYUI_AUTH_TOKEN` | | Generic auth token for a **self-hosted ComfyUI behind a reverse proxy / API gateway** (distinct from Comfy Cloud). When set, attached to every ComfyUI request. Never logged. |
  442. | `COMFYUI_AUTH_HEADER` | `Authorization` | Header name for `COMFYUI_AUTH_TOKEN` (e.g. `X-API-Key`). |
  443. | `COMFYUI_AUTH_SCHEME` | `Bearer` for `Authorization`, else none | Scheme prefix on the token value (e.g. `Bearer`, `Token`). |
  444. | `CIVITAI_API_TOKEN` | | CivitAI API token for model downloads |
  445. | `HUGGINGFACE_TOKEN` | | HuggingFace token for higher API rate limits |
  446. | `COMFYUI_DOWNLOAD_PROXY` | | Optional HTTP/HTTPS proxy for model-download traffic only; standard proxy environment variables and static Windows WinINet settings are also honored |
  447. | `GITHUB_TOKEN` | | GitHub token for skill generation (avoids rate limits) |
  448. | `REGISTRY_ACCESS_TOKEN` | | Comfy Registry API key for `node_pack` (`action: "publish"`) (env-only, never logged) |
  449. | `COMFYUI_DOWNLOAD_CACHE_DIR` | `~/.comfyui-mcp/cache` | Content-addressed model-download cache (dedup + concurrent coalescing) |
  450. | `COMFYUI_LRU_CACHE_SIZE_GB` | `0` | Cap the download cache in GB; `0` disables LRU eviction |
  451. | `COMFYUI_STARTUP_CHECK_INTERVAL_S` / `…_MAX_TRIES` | `1` / `60` | Readiness-probe interval + max tries when starting a local ComfyUI |
  452. | `COMFYUI_ALWAYS_RESTART` | `false` | Auto-restart a crashed local ComfyUI (bounded by `COMFYUI_RESTART_MAX_ATTEMPTS` / `COMFYUI_RESTART_WINDOW_S`) |
  453. | `COMFYUI_MCP_STALL_S` | `180` | Render-wedge watchdog: seconds a sampler step can re-emit the same progress before a STALL/BACKLOG note is prepended to the agent's next turn (clamped 15–3600s; live-tunable from the panel) |
  454. | `COMFYUI_MCP_INTERRUPT_S` | `30` | Seconds `queue` (action:"cancel") waits for an interrupt to actually stop a job before escalating to `/free` and reporting it wedged |
  455. | `LOG_LEVEL` | `info` | Logging verbosity: `debug`, `info`, `warn`, `error` |
  456. ### Transports
  457. The server speaks stdio by default, which is what Claude Code, Claude Desktop, and the MCP Inspector expect, so no flags are needed. For MCP gateways, remote/hosted setups, or `fetch`-based clients, opt into streamable-HTTP:
  458. ```bash
  459. # stdio (default)
  460. npx -y comfyui-mcp@latest
  461. # streamable-HTTP on http://127.0.0.1:9100/mcp
  462. npx -y comfyui-mcp@latest --http
  463. npx -y comfyui-mcp@latest --http --host 0.0.0.0 --port 9100 # bind/port overrides
  464. ```
  465. | Flag | Env | Default | Description |
  466. |------|-----|---------|-------------|
  467. | `--http` / `--transport http` | `MCP_TRANSPORT=http` | `stdio` | Serve streamable-HTTP at `/mcp` instead of stdio |
  468. | `--host <h>` | `MCP_HOST` | `127.0.0.1` | HTTP bind host (use `0.0.0.0` to expose) |
  469. | `--port <n>` | `MCP_PORT` | `9100` | HTTP port |
  470. | `--comfyui-url <url>` | `COMFYUI_URL` | *(auto-detect)* | Target a specific (incl. remote) ComfyUI |
  471. | `--force-remote` | `COMFYUI_MCP_FORCE_REMOTE` | `false` | Force remote mode for a loopback `--comfyui-url` (e.g. dstack/RunPod port-forwards to `localhost`) |
  472. ### Other agents & local LLMs (Hermes, OpenClaw, Copilot CLI, Ollama)
  473. comfyui-mcp supports non-Claude harnesses. One command
  474. writes the server entry into the harness's own config (it merges into an existing
  475. file rather than overwriting it):
  476. ```bash
  477. npx -y comfyui-mcp setup hermes # → ~/.hermes/config.yaml (compact by default)
  478. npx -y comfyui-mcp setup openclaw # → ~/.openclaw/openclaw.json (compact by default)
  479. npx -y comfyui-mcp setup copilot # → ~/.copilot/mcp-config.json (full by default)
  480. # flags: --compact | --full, --comfyui-url <url>, --dry-run
  481. ```
  482. **Model requirements.** Tool calling is a hard requirement; a model without tool calling
  483. doesn't work. Thinking and vision are recommended. Without
  484. thinking, multi-step tool chains degrade; without vision the agent can
  485. generate but can't see its own outputs.
  486. **Compact tool mode.** `--compact` /
  487. `COMFYUI_MCP_TOOL_MODE=compact` registers 3 meta-tools (`list_tools` →
  488. `describe_tool` → `call_tool`) instead of the direct tool set, pulling schemas
  489. into context one tool at a time. That is the right trade for small local models. The
  490. direct tool set is the default and is what frontier-model harnesses want.
  491. **Run it locally
  492. for free with our fine-tuned models.** `ollama pull artokun/gemma4-comfyui-mcp:e4b`
  493. (also `:e2b` for ~2 GB VRAM, `:12b` for ~8 GB) is Gemma 4, QLoRA-trained on 1,055
  494. server-verified trajectories over the full comfyui-mcp tool set, and is the
  495. panel's Ollama default. Stock `gemma4:*`/`qwen3:4b` are also validated end-to-end
  496. (`npm run test:local-llm`); gemma3 has no native tool calling and is
  497. unsupported. The full guide, covering hosted-model guidance (DeepSeek/MiMo/GLM class),
  498. per-harness setup, and troubleshooting, is
  499. **[Local LLMs & other agents](https://comfyui-mcp.artokun.io/docs/local-llms)**.
  500. | Flag | Env | Default | Description |
  501. |------|-----|---------|-------------|
  502. | `setup <agent>` | | | Write the comfyui entry into hermes / openclaw / copilot config, then exit |
  503. | `--compact` / `--tool-mode compact` | `COMFYUI_MCP_TOOL_MODE=compact` | `full` | Opt into the 3 meta-tools (`list_tools` / `describe_tool` / `call_tool`) instead of the direct tool set — recommended for small local models. `--full` is still accepted and is now a no-op |
  504. ### Remote ComfyUI
  505. Point the server at a ComfyUI running anywhere; no local install is required:
  506. ```bash
  507. npx -y comfyui-mcp@latest --comfyui-url http://192.168.1.50:8188
  508. npx -y comfyui-mcp@latest --http --comfyui-url https://comfy.example.com:8443
  509. ```
  510. **Behind a reverse proxy / API gateway** (path prefix + auth header). For a
  511. self-hosted ComfyUI exposed under a prefixed route with its own auth layer (this
  512. is *not* Comfy Cloud, which is `COMFYUI_API_KEY`):
  513. ```bash
  514. COMFYUI_URL=https://gateway.example.com/comfyapi \
  515. COMFYUI_AUTH_TOKEN=your-token \
  516. npx -y comfyui-mcp@latest --http # → Authorization: Bearer your-token, requests under /comfyapi
  517. # custom header / scheme:
  518. COMFYUI_URL=https://gateway.example.com/comfyapi \
  519. COMFYUI_AUTH_HEADER=X-API-Key COMFYUI_AUTH_TOKEN=your-token \
  520. npx -y comfyui-mcp@latest --http # → X-API-Key: your-token
  521. ```
  522. ### Auto-detection
  523. **Port**: Probes `8188` (CLI default) then `8000` (Desktop app default) via `/system_stats`.
  524. **Path**: Checks common locations in order:
  525. - `~/Documents/ComfyUI` (macOS/Windows Desktop app data directory)
  526. - `~/Library/Application Support/ComfyUI` (macOS)
  527. - `~/AppData/Local/Programs/ComfyUI/resources/ComfyUI` (Windows Desktop app install)
  528. - `~/AppData/Local/ComfyUI` (Windows)
  529. - `~/ComfyUI`, `~/code/ComfyUI`, `~/projects/ComfyUI`, `~/src/ComfyUI`
  530. - `/opt/ComfyUI`, `~/.local/share/ComfyUI` (Linux)
  531. - Scans `~/Documents` and `~/My Documents` for any directory containing "ComfyUI"
  532. Set `COMFYUI_PATH` to skip detection and use an explicit path.
  533. ---
  534. ## How It Works
  535. The server communicates with ComfyUI through its REST API and WebSocket interface:
  536. - **WebSocket.** Enqueue workflows, receive real-time progress updates (step by step via the background monitor script), get execution results
  537. - **REST API.** System stats, node definitions (`/object_info`), logs, history, queue management, workflow library, VRAM control (`/free`), embeddings
  538. - **File system.** Read/write the models directory, detect installation paths, upload images, extract PNG metadata, browse outputs
  539. - **External APIs.** HuggingFace (model search), ComfyUI Registry (custom node discovery), GitHub (skill generation), CivitAI (model downloads)
  540. All communication with the MCP client (Claude Code) happens over stdio using the [Model Context Protocol](https://modelcontextprotocol.io). Logs go to stderr so they never mix into the protocol stream.
  541. ---
  542. ## Development
  543. ### Prerequisites
  544. - [Node.js](https://nodejs.org) 22.14 or later in the 22.x line, or 24+. The native SQLite dependency requires Node-API 10; earlier Node 22 releases and Node 23 are not supported.
  545. - [ComfyUI](https://github.com/comfyanonymous/ComfyUI) running locally
  546. ### Setup
  547. ```bash
  548. git clone https://github.com/artokun/comfyui-mcp.git
  549. cd comfyui-mcp
  550. npm install
  551. ```
  552. ### Scripts
  553. | Script | Description |
  554. |--------|-------------|
  555. | `npm run dev` | Run from source with tsx (hot reload) |
  556. | `npm run build` | Compile TypeScript to `dist/` |
  557. | `npm start` | Run compiled output |
  558. | `npm test` | Run unit tests (vitest) |
  559. | `npm run test:integration` | Run integration tests (requires running ComfyUI) |
  560. | `npm run lint` | Type-check without emitting |
  561. | `npm run generations:stats` | Show local generation tracking statistics |
  562. | `npm run sync-agents` | Sync Claude skills/commands/hooks to Google Antigravity, OpenCode, and other AI IDE formats that supports .agents files |
  563. ### Local testing with Claude Code
  564. Point Claude Code at your local build instead of the npm package:
  565. ```json
  566. {
  567. "mcpServers": {
  568. "comfyui": {
  569. "command": "node",
  570. "args": ["/path/to/comfyui-mcp/dist/index.js"],
  571. "env": {}
  572. }
  573. }
  574. }
  575. ```
  576. Or test the plugin directly:
  577. ```bash
  578. claude --plugin-dir ./plugin
  579. ```
  580. ### Project structure
  581. ```
  582. scripts/
  583. generation-stats.mjs # CLI: npm run generations:stats
  584. src/
  585. index.ts # MCP server entry point (stdio transport)
  586. config.ts # Auto-detection & environment config
  587. comfyui/
  588. client.ts # ComfyUI WebSocket/HTTP client wrapper
  589. types.ts # TypeScript interfaces
  590. services/
  591. workflow-executor.ts # Execute workflows, handle images & errors
  592. workflow-composer.ts # Templates (txt2img, img2img, upscale, inpaint)
  593. workflow-validator.ts # Dry-run validation (missing nodes, models, connections)
  594. image-management.ts # Upload images, extract PNG metadata, list outputs
  595. mermaid-converter.ts # Workflow → Mermaid diagram
  596. workflow-converter.ts # UI → API: de-virtualize Get/Set buses + Reroutes, expand subgraphs, resolve bypass (powers get_workflow's strip action)
  597. workflow-slicer.ts # sliceWorkflow() — rgthree Fast-Groups-Bypass pipeline un-chunker (shared by the CLI + get_workflow's slice action)
  598. mermaid-parser.ts # Mermaid diagram → Workflow
  599. model-resolver.ts # HuggingFace search, local models, downloads
  600. generation-tracker.ts # SQLite generation log, settings dedup, stats
  601. file-hasher.ts # SHA256 hashing of .safetensors with cache
  602. workflow-settings-extractor.ts # Extract settings from workflow JSON
  603. process-control.ts # Stop, start, restart ComfyUI process
  604. registry-client.ts # ComfyUI Registry API
  605. skill-generator.ts # Generate node pack skill docs
  606. tools/ # MCP tool registration (one file per group)
  607. workflow-execute.ts # enqueue_workflow, get_system_stats
  608. workflow-visualize.ts # visualize_workflow (render/render_hierarchical/mermaid/to_dsl/from_dsl)
  609. workflow-compose.ts # create_workflow (create/modify/validate/node_info)
  610. workflow-validate.ts # the validate action's body
  611. workflow-library.ts # get_workflow (8 read actions), save_workflow (save/lock/verify_lock)
  612. image-management.ts # get_image (7 read actions), upload_image (5 write actions)
  613. model-management.ts # download_model, list_local_models (the two consolidated model tools)
  614. memory-management.ts # clear_vram
  615. registry-search.ts # search_custom_nodes (search/details)
  616. node-management.ts # install_custom_node (install/update/fix/uninstall/enable/disable/list/…)
  617. node-pack.ts # node_pack (scaffold/verify/publish/read/write/patch/git/…)
  618. generation-tracker.ts # the get_history suggest/stats jobs
  619. diagnostics.ts # get_system_stats (action:"logs"), get_history
  620. process-control.ts # restart_comfyui (restart/start/stop)
  621. index.ts # Registers all tool groups
  622. utils/
  623. errors.ts # Custom error hierarchy with MCP integration
  624. logger.ts # stderr-only logging (safe for stdio transport)
  625. image.ts # Base64 encoding utilities
  626. plugin/
  627. .claude-plugin/ # Plugin manifest
  628. .mcp.json # MCP server config for plugin
  629. commands/ # Slash commands
  630. gen.md # /comfy:gen — image generation
  631. viz.md # /comfy:viz — workflow visualization
  632. node-skill.md # /comfy:node-skill — skill generation
  633. debug.md # /comfy:debug — failure diagnosis
  634. batch.md # /comfy:batch — parameter sweeps
  635. convert.md # /comfy:convert — format conversion
  636. install.md # /comfy:install — node pack installation
  637. gallery.md # /comfy:gallery — output browser
  638. compare.md # /comfy:compare — workflow diff
  639. recipe.md # /comfy:recipe — multi-step pipelines
  640. skills/ # Knowledge bases
  641. comfyui-core/ # Workflow format, node types, pipeline patterns
  642. prompt-engineering/ # CLIP syntax, model-specific prompting
  643. troubleshooting/ # Error catalog with patterns and fixes
  644. model-compatibility/ # Compatibility matrix per model family
  645. agents/ # Autonomous agents
  646. explorer.md # Research custom node packs, generate skills
  647. debugger.md # Diagnose workflow failures
  648. optimizer.md # Analyze and optimize workflows
  649. hooks/ # Pre/post tool-use hooks
  650. hooks.json # Hook configuration
  651. vram-check.mjs # VRAM watchdog before execution
  652. save-warning.mjs # Save prompt before stop/restart
  653. job-complete-notify.mjs # Job completion notification via temp files
  654. scripts/ # Background scripts
  655. monitor-progress.mjs # Real-time WebSocket progress monitor
  656. launch-server.mjs # MCP server launcher — global install if present, else npx with a
  657. # cold-start handshake rescue so a first run cannot time out (#1447)
  658. ```
  659. ---
  660. ## Troubleshooting
  661. **"ComfyUI not detected on ports 8188, 8000"**
  662. Make sure ComfyUI is running. The Desktop app uses port 8000 by default; the CLI uses 8188. Set `COMFYUI_PORT` if you're using a custom port.
  663. **"COMFYUI_PATH is not configured"**
  664. The auto-detection couldn't find your ComfyUI data directory. Set `COMFYUI_PATH` to the directory containing your `models/` folder (e.g., `~/Documents/ComfyUI`).
  665. **"Multiple ComfyUI installations detected"**
  666. This is informational. The server uses the first one found. Set `COMFYUI_PATH` to pick a specific installation.
  667. **Model downloads fail**
  668. For HuggingFace gated models, set `HUGGINGFACE_TOKEN`. For CivitAI, set `CIVITAI_API_TOKEN`.
  669. **Workflow execution errors**
  670. Use `/comfy:debug` to diagnose failures. Or call `get_history` (`action: "diagnose"`) / `get_system_stats (action:"logs")` directly to see the full error messages, including Python tracebacks from ComfyUI.
  671. **Out of memory (OOM)**
  672. Use `clear_vram` to free GPU memory before running large workflows. The VRAM watchdog hook warns you when less than 1GB is free before a workflow runs. See the **troubleshooting** skill for model-specific VRAM estimates.
  673. **Missing custom nodes**
  674. Use `/comfy:install <pack>` to install missing node packs from the registry. The debug command detects missing packs and suggests them.
  675. ---
  676. ## Contributing
  677. Contributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the dev setup, project
  678. conventions, how to add an MCP tool, and the release process.
  679. Quick version: fork → branch (`feat/my-feature`) → make changes (make sure `npm run build` and
  680. `npm test` pass; run `npm run docs:gen` if you touched tools) → open a PR.
  681. ---
  682. ## Maintainer
  683. Built and maintained by [**@artokun**](https://github.com/artokun), a regular contributor across the Comfy-Org ecosystem:
  684. - **[Comfy-Org/ComfyUI_frontend](https://github.com/Comfy-Org/ComfyUI_frontend/pulls?q=is%3Apr+author%3Aartokun).** 10 merged PRs, mostly on the v2 graph renderer: subgraph rendering, promoted-widget plumbing, viewport persistence, with backports across `cloud/1.41`, `cloud/1.42`, `core/1.41`, and `core/1.42`.
  685. - **[Comfy-Org/ComfyUI](https://github.com/Comfy-Org/ComfyUI/pulls?q=is%3Apr+author%3Aartokun)** (core). Crash fixes in the Python backend's video/audio save path ([#12683](https://github.com/Comfy-Org/ComfyUI/pull/12683), [#12550](https://github.com/Comfy-Org/ComfyUI/pull/12550)).
  686. If you're at Comfy-Org (or hiring around the ComfyUI ecosystem), I'd love to chat. Email me at **[art.longbottom.jr@gmail.com](mailto:art.longbottom.jr@gmail.com)**.
  687. ---
  688. ## License
  689. MIT. See [LICENSE](./LICENSE) for details.
  690. ---
  691. ## Changelog
  692. See [CHANGELOG.md](./CHANGELOG.md) for the full, structured release history.

Ratings and comments

Sign in to rate this skill.

Sign in

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