{"id":44826426,"url":"https://github.com/artokun/comfyui-mcp","last_synced_at":"2026-07-02T01:00:33.334Z","repository":{"id":338656297,"uuid":"1158621117","full_name":"artokun/comfyui-mcp","owner":"artokun","description":"The local-first, agent-native control plane for ComfyUI — MCP server + Claude Code plugin. 108 tools, 29 AI skills (Flux · WAN · LTX video · Qwen · Z-Image). Author \u0026 run workflows, edit your live graph in natural language, manage models \u0026 custom nodes. Local, LAN, VPS, or Comfy Cloud.","archived":false,"fork":false,"pushed_at":"2026-06-30T00:19:26.000Z","size":29261,"stargazers_count":208,"open_issues_count":1,"forks_count":35,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-30T00:22:21.724Z","etag":null,"topics":["agent-skills","ai-agent","claude-code","claude-plugin","claude-skills","comfyui","comfyui-extension","comfyui-mcp","comfyui-mcp-server","flux","image-generation","local-first","mcp","mcp-server","model-context-protocol","qwen","stable-diffusion","text-to-image","video-generation","wan"],"latest_commit_sha":null,"homepage":"https://comfyui-mcp.artokun.io/docs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/artokun.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-15T17:08:48.000Z","updated_at":"2026-06-30T00:18:36.000Z","dependencies_parsed_at":"2026-02-16T00:01:51.809Z","dependency_job_id":null,"html_url":"https://github.com/artokun/comfyui-mcp","commit_stats":null,"previous_names":["artokun/comfyui-mcp"],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/artokun/comfyui-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artokun%2Fcomfyui-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artokun%2Fcomfyui-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artokun%2Fcomfyui-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artokun%2Fcomfyui-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/artokun","download_url":"https://codeload.github.com/artokun/comfyui-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artokun%2Fcomfyui-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35028642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agent","claude-code","claude-plugin","claude-skills","comfyui","comfyui-extension","comfyui-mcp","comfyui-mcp-server","flux","image-generation","local-first","mcp","mcp-server","model-context-protocol","qwen","stable-diffusion","text-to-image","video-generation","wan"],"created_at":"2026-02-16T22:22:13.026Z","updated_at":"2026-07-02T01:00:33.232Z","avatar_url":"https://github.com/artokun.png","language":"TypeScript","funding_links":[],"categories":["Source Catalog"],"sub_categories":[],"readme":"# comfyui-mcp — the Claude Code plugin for ComfyUI\n\n**Claude Code plugin + MCP server for [ComfyUI](https://github.com/comfyanonymous/ComfyUI)** — generate images and video, execute and author workflows, manage models and custom nodes, and **edit your live ComfyUI graph from your Claude session** ([sidebar panel](https://github.com/artokun/comfyui-mcp-panel), zero API keys).\n\n[![npm version](https://img.shields.io/npm/v/comfyui-mcp)](https://www.npmjs.com/package/comfyui-mcp)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org)\n[![License](https://img.shields.io/npm/l/comfyui-mcp)](./LICENSE)\n[![Documentation](https://img.shields.io/badge/docs-comfyui--mcp.artokun.io-2563EB?logo=readthedocs\u0026logoColor=white)](https://comfyui-mcp.artokun.io/docs)\n\n[![comfyui-mcp MCP server](https://glama.ai/mcp/servers/artokun/comfyui-mcp/badges/card.svg)](https://glama.ai/mcp/servers/artokun/comfyui-mcp)\n[![comfyui-mcp MCP server](https://glama.ai/mcp/servers/artokun/comfyui-mcp/badges/score.svg)](https://glama.ai/mcp/servers/artokun/comfyui-mcp)\n\nWorks on **macOS**, **Linux**, and **Windows**. Auto-detects your ComfyUI installation and port.\n\n**108 MCP tools** | **22 AI skills** (Flux · WAN · LTX 2.3 video · Qwen · Z-Image · Ideogram 4 · ERNIE · ANIMA · model registry · Civitai · node authoring) | **13 installer packs** | **11 slash commands** | **4 autonomous agents** | **4 hooks**\n\nThe plugin ships **expert skills that grow with every release** — model-specific generation guides with curated download URLs, workflow recipes, troubleshooting, and custom-node authoring — so Claude knows the right sampler, CFG, resolution, and model files for each architecture without trial and error.\n\n\u003e ### ✅ Now available: the [ComfyUI Agent Panel](https://registry.comfy.org/nodes/comfyui-agent-panel) on ComfyUI-Manager \u0026 the Comfy Registry\n\u003e An autonomous AI agent in your ComfyUI sidebar — **now on Claude OR ChatGPT** (your own subscription, no API key), at full feature parity. 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 — and it asks before spending paid API credits.\n\u003e Search **`comfyui-agent-panel`** in ComfyUI-Manager to install. [Read more →](https://comfyui-mcp.artokun.io/docs/panel)\n\n📖 **Full documentation: [comfyui-mcp.artokun.io/docs](https://comfyui-mcp.artokun.io/docs)**\n\n---\n\n## Quick Start\n\n**1. Install ComfyUI** (if you haven't already): [ComfyUI Desktop](https://www.comfy.org/download) or [from source](https://github.com/comfyanonymous/ComfyUI)\n\n**2. Add the MCP server** to your Claude Code config (`~/.claude/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"comfyui\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"comfyui-mcp\"],\n      \"env\": {\n        \"CIVITAI_API_TOKEN\": \"\"\n      }\n    }\n  }\n}\n```\n\n**3. Start using it.** With ComfyUI running, ask Claude to generate an image:\n\n```\n\u003e Generate an image of a sunset over mountains\n```\n\nClaude will find (or download) a checkpoint, build a workflow, execute it, and return the image.\n\n\u003e **Note**: This runs as a standalone MCP server — no need to clone this repo. `npx` will download and run it automatically.\n\n### Scope: local, remote, or Comfy Cloud\n\n`comfyui-mcp` is the community MCP for **local** and **remote** ComfyUI (Mac/Linux/Windows installs, RunPod, VPS, LAN, etc.) — that's the primary target.\n\nFor **Comfy Cloud** users, [Comfy-Org ships an official Comfy Cloud MCP](https://docs.comfy.org/development/cloud/mcp-server) (currently invite-only beta) which is cloud-exclusive and maintained by the Comfy team. `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; pick whichever fits your workflow.\n\n### Remote / hosted connector (one command)\n\nWant to use `comfyui-mcp` from **Claude Desktop's Custom Connectors** or any remote\nclient — like Comfy's own `cloud.comfy.org/mcp` connector? Run it as an\nauthenticated, publicly-reachable Streamable-HTTP server with one flag:\n\n```bash\nnpx -y comfyui-mcp --tunnel\n```\n\nThis forces the HTTP transport, generates an auth token, opens a\n[cloudflared](https://github.com/cloudflare/cloudflared) quick tunnel, and prints\na ready-to-paste `https://…/mcp` URL + token + Claude Desktop connector snippet.\nAuth accepts `Authorization: Bearer \u003ctoken\u003e` **or** `X-API-Key: \u003ctoken\u003e` (matching\nComfy Cloud's convention). See the\n[Remote / hosted connector guide](https://comfyui-mcp.artokun.io/docs/remote-connector)\nfor the full walkthrough and headless usage.\n\n\u003e Auth is opt-in: with no `COMFYUI_MCP_HTTP_TOKEN` set and no `--tunnel`, the\n\u003e default stdio (and plain `--http` on loopback) behavior is unchanged — open and\n\u003e local. OAuth (Comfy's browser sign-in flow) is a planned follow-up.\n\n---\n\n## Claude Code Plugin\n\nThis package also ships as a **Claude Code plugin**, providing slash commands, skills, agents, and hooks on top of the MCP tools.\n\n### Install as a plugin\n\n```bash\n# In Claude Code\n/plugin marketplace add artokun/comfyui-mcp\n/plugin install comfy\n```\n\n### Slash commands\n\n| Command | Description |\n|---------|-------------|\n| `/comfy:gen \u003cprompt\u003e` | Generate an image from a text description — auto-selects checkpoint, builds workflow, returns image |\n| `/comfy:viz \u003cworkflow\u003e` | Visualize a workflow as a Mermaid diagram with nodes grouped by category |\n| `/comfy:node-skill \u003cpack\u003e` | Generate a Claude skill for a custom node pack from Registry ID or GitHub URL |\n| `/comfy:debug [prompt_id]` | Diagnose why a workflow failed — reads history, logs, traces root cause, suggests fixes |\n| `/comfy:batch \u003cprompt, params\u003e` | Parameter sweep generation across cfg, sampler, steps, seed, etc. |\n| `/comfy:convert \u003cfile\u003e` | Convert between UI format and API format workflows |\n| `/comfy:install \u003cpack\u003e` | Install a custom node pack — git clone, pip install, optional restart |\n| `/comfy:gallery [filter]` | Browse generated outputs with metadata — filter by date, count, or filename |\n| `/comfy:compare \u003ca vs b\u003e` | Diff two workflows side by side — shows added/removed nodes and changed parameters |\n| `/comfy:recipe \u003cname\u003e \u003cprompt\u003e` | Multi-step recipes: `portrait`, `hires-fix`, `style-transfer`, `product-shot` |\n\n### Built-in skills\n\n22 skills total — model-family guides (Flux, WAN, LTX 2.3, 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, and the core four below. Full list on the [plugin docs page](https://comfyui-mcp.artokun.io/docs/plugin).\n\n\u003e **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).\n\n| Skill | Description |\n|-------|-------------|\n| **comfyui-core** | Workflow format, node types, data flow patterns, pipeline architecture, MCP tool usage guide |\n| **prompt-engineering** | CLIP weight syntax `(word:1.3)`, BREAK tokens, embeddings, model-specific prompting for SD1.5/SDXL/Flux/SD3 |\n| **troubleshooting** | Common error catalog — OOM, dtype mismatches, missing nodes, NaN tensors, black images, CUDA errors, with VRAM estimates per model |\n| **model-compatibility** | Compatibility matrix — loaders, resolutions, CFG, samplers, ControlNets, LoRAs, and VAEs per model family (SD1.5/SDXL/Turbo/Lightning/Flux/SD3/LTXV) |\n\n### Agents\n\n| Agent | Model | Description |\n|-------|-------|-------------|\n| **comfy-explorer** | Sonnet | Researches custom node packs — reads docs, queries `/object_info`, generates comprehensive skill files |\n| **comfy-debugger** | Sonnet | Autonomously diagnoses workflow failures — gathers logs + history, identifies failing node, checks models + custom nodes, proposes and optionally applies fixes |\n| **comfy-optimizer** | Sonnet | Analyzes workflows for performance — detects redundant nodes, VRAM waste, wrong CFG/steps for model family, precision issues, suggests optimizations |\n\n### Hooks\n\n| Event | Trigger | Action |\n|-------|---------|--------|\n| PreToolUse | `enqueue_workflow` | **VRAM watchdog** — checks GPU memory via `/system_stats` and warns if \u003c 1GB free before execution |\n| PreToolUse | `stop_comfyui`, `restart_comfyui` | **Save warning** — prompts user to save unsaved workflow changes before stopping ComfyUI |\n| PostToolUse | Any comfyui tool | **Job completion notify** — checks for completed jobs and injects completion summaries into the conversation |\n\n### Background Scripts\n\n| Script | Description |\n|--------|-------------|\n| `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 `get_job_status` in a loop. |\n\n---\n\n## Panel agent (Claude or ChatGPT)\n\nBeyond the headless MCP server, this package ships the **panel orchestrator** that\npowers the **[ComfyUI Agent Panel](https://github.com/artokun/comfyui-mcp-panel)** —\nan autonomous agent embedded in ComfyUI's sidebar that drives the live canvas. It\nruns in the background on **your own subscription** (Claude *or* ChatGPT), started\non demand by the panel's **Connect** button:\n\n```bash\nnpx -y comfyui-mcp --panel-orchestrator\n```\n\n**Multi-provider, full parity.** The orchestrator depends on a provider-neutral\n**`AgentBackend`** port (dependency injection), with two adapters:\n\n- **`ClaudeBackend`** — the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)\n  (`@anthropic-ai/claude-agent-sdk`), a persistent streaming session over the\n  claude.ai subscription (OAuth, no key).\n- **`CodexBackend`** — OpenAI Codex over the **`codex app-server`** JSON-RPC\n  protocol (`@openai/codex`), on the ChatGPT subscription (`codex login`, no key).\n\nBoth are optional dependencies, and the panel picks a **provider, not a port** —\neach backend runs its own orchestrator on its own loopback bridge port. A\ncapability matrix lets the panel degrade gracefully (e.g. conversation-rollback is\nClaude-only today, since the Codex app-server resumes whole threads only).\n\n**The live-canvas tools and model knowledge are identical across providers.** The\n`panel_*` tool definitions live in **one shared list**, registered onto both the\nin-process Claude SDK MCP server *and* a `@modelcontextprotocol/sdk` server over a\nloopback **streamable-HTTP MCP** that the orchestrator hosts for Codex (which can\nonly host config-declared MCP servers). The headless `comfyui` MCP is likewise\ninjected into both — in-process for Claude, declared via `codex app-server -c\nmcp_servers` for ChatGPT — so generation, models, and workflow tools are the same\neverywhere.\n\nNew tools that give every backend the same expertise and a cost guardrail:\n\n| Tool | Description |\n|------|-------------|\n| `list_skills` / `read_skill` | Discover and read bundled model-family + workflow skills — the knowledge Claude loads natively, exposed to any MCP client (e.g. the Codex backend) |\n| `list_packs` / `read_pack_workflow` | List one-command installer packs (custom nodes + weights + ready workflow; all local-GPU / free) and read a pack's graph |\n| `list_workflow_templates` | List the connected ComfyUI's official workflow templates (the templates package + custom-node-provided templates) |\n| `check_workflow_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 |\n| `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 |\n| `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 |\n\nSee the design doc — **[docs/design/agent-backend-injection.md](docs/design/agent-backend-injection.md)** —\nfor the port, the capability matrix, and the per-provider \"clink\" points, and the\n**[panel docs](https://comfyui-mcp.artokun.io/docs/panel)** for the full sidebar UX.\n\n---\n\n## MCP Tools\n\n108 tools across workflow execution, generation, iteration, composition, models, and more:\n\n### Image Generation (high-level)\n\n| Tool | Description |\n|------|-------------|\n| `generate_image` | Generate from a text prompt — builds a txt2img workflow, fills unspecified params from your defaults, auto-selects a checkpoint |\n| `generate_with_controlnet` | Generate conditioned by a ControlNet image (pose/depth/canny/normal) + prompt |\n| `generate_with_ip_adapter` | Generate guided by a reference image's style/subject via IP-Adapter (needs ComfyUI_IPAdapter_plus) |\n\n### Audio Generation (high-level)\n\n| Tool | Description |\n|------|-------------|\n| `generate_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 |\n\n### Assets \u0026 Iteration\n\n| Tool | Description |\n|------|-------------|\n| `view_image` | Return a generated asset's bytes as an inline image so the agent can see the result |\n| `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 |\n| `regenerate` | Re-run the workflow that produced an `asset_id`, with optional parameter overrides |\n| `list_assets` | Browse recently generated assets (newest-first) by `asset_id` |\n| `get_asset_metadata` | Full provenance for an asset, including the originating workflow |\n\n### Defaults\n\n| Tool | Description |\n|------|-------------|\n| `get_defaults` | Show merged generation defaults with per-source attribution |\n| `set_defaults` | Update runtime defaults; `persist: true` writes the config file |\n\n### Workflow Execution\n\n| Tool | Description |\n|------|-------------|\n| `enqueue_workflow` | Submit a workflow (API format JSON) — returns `prompt_id` immediately, non-blocking |\n| `get_job_status` | Check execution status of a job by prompt ID |\n| `get_queue` | View the current execution queue (running + pending) |\n| `get_queued_workflow` | Inspect the full workflow payload for one pending queue item |\n| `move_queued_job` | Move a pending job to the front/back by requeueing it with a new prompt ID |\n| `edit_queued_job` | Patch or replace a pending queued workflow and requeue it with a new prompt ID |\n| `cancel_job` | Interrupt the currently running job — escalates (interrupt → verify → `/free`) and reports WEDGED if it won't die; `clear_pending: true` also drops all pending jobs in the same call |\n| `get_system_stats` | Get system info — GPU, VRAM, Python version, OS |\n\n### Workflow Visualization\n\n| Tool | Description |\n|------|-------------|\n| `visualize_workflow` | Convert a workflow to a Mermaid flowchart with nodes grouped by category |\n| `mermaid_to_workflow` | Convert a Mermaid diagram back to executable workflow JSON |\n\n### Workflow Composition\n\n| Tool | Description |\n|------|-------------|\n| `create_workflow` | Generate a workflow from templates: `txt2img`, `img2img`, `upscale`, `inpaint`, `controlnet`, `ip_adapter`, `ace_step_15`, `stable_audio_3` |\n| `modify_workflow` | Apply operations: `set_input`, `add_node`, `remove_node`, `connect`, `insert_between` |\n| `get_node_info` | Query available node types from ComfyUI's `/object_info` endpoint |\n\n### Workflow Validation\n\n| Tool | Description |\n|------|-------------|\n| `validate_workflow` | Dry-run validation — checks missing nodes, broken connections, invalid output indices, missing model files |\n\n### Workflow Library\n\n| Tool | Description |\n|------|-------------|\n| `list_workflows` | List saved workflows from ComfyUI's user library |\n| `get_workflow` | Load a specific saved workflow by filename |\n| `strip_workflow` | **De-virtualize** any workflow (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. |\n| `slice_workflow` | **Un-chunk** a toggle-template monolith — slice ONE rgthree Fast-Groups-Bypass-toggled pipeline out into a standalone activated graph (seed from the named groups' output nodes, backward-closure, un-bypass). Pair with `strip_workflow` to then flatten the buses. |\n| `save_workflow` | Save a workflow to the ComfyUI user library |\n\n### Image Management\n\n| Tool | Description |\n|------|-------------|\n| `upload_image` | Copy a local image into ComfyUI's `input/` directory for img2img, inpaint, or ControlNet |\n| `workflow_from_image` | Extract embedded workflow metadata from a ComfyUI-generated PNG (reads `prompt` and `workflow` tEXt chunks) |\n| `list_output_images` | 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` |\n\n### Model Management\n\n| Tool | Description |\n|------|-------------|\n| `search_models` | Search HuggingFace for compatible models (checkpoints, LoRAs, VAEs, etc.) |\n| `download_model` | Download a model from a URL to the correct ComfyUI subdirectory |\n| `list_local_models` | List installed models by type: checkpoints, loras, vae, upscale_models, controlnet, embeddings, clip, unet, diffusion_models, text_encoders |\n| `list_extra_paths` | View standalone or Desktop ComfyUI extra search-path config |\n| `add_extra_path` | Add a model/custom_nodes search path to the extra paths YAML |\n| `remove_extra_path` | Remove a stored extra search path from the extra paths YAML |\n\n### Memory Management\n\n| Tool | Description |\n|------|-------------|\n| `clear_vram` | Free GPU VRAM by unloading cached models — calls ComfyUI's `/free` endpoint, reports before/after stats |\n| `get_embeddings` | List installed textual inversion embeddings |\n\n### Registry \u0026 Discovery\n\n| Tool | Description |\n|------|-------------|\n| `search_custom_nodes` | Search the ComfyUI Registry for custom node packs by keyword |\n| `get_node_pack_details` | Get full details of a custom node pack (description, author, nodes, install info) |\n| `generate_node_skill` | Generate a Claude skill `.md` file from a Registry ID or GitHub URL |\n\n### Diagnostics\n\n| Tool | Description |\n|------|-------------|\n| `get_logs` | Get ComfyUI server logs with optional keyword filter (e.g., `error`, `warning`, a node name) |\n| `get_history` | Get execution history with full error details, Python tracebacks, timing, and cached node info |\n\n### Process Control\n\n| Tool | Description |\n|------|-------------|\n| `stop_comfyui` | Stop the running ComfyUI process (saves PID and launch args for restart) |\n| `start_comfyui` | Start ComfyUI using info saved from a previous stop |\n| `restart_comfyui` | Stop and restart ComfyUI, preserving all launch arguments |\n\n### Generation Tracker\n\n| Tool | Description |\n|------|-------------|\n| `suggest_settings` | Suggest proven sampler/scheduler/steps/CFG settings from local generation history — query by model family, LoRA hash, or text search |\n| `generation_stats` | Show local generation tracking statistics — total runs, unique combos, breakdown by model family |\n\nEvery `enqueue_workflow` call automatically logs settings to a local SQLite database (`generations.db`). Same settings combos get a `reuse_count` bump instead of duplicates, creating a natural popularity signal. Models and LoRAs are identified by content hash (AutoV2 / SHA256), not filenames — so renamed files still group together.\n\n```bash\n# View local stats from the CLI\nnpm run generations:stats\n```\n\n### Model Settings\n\nCommunity-maintained preset library (`model-settings.json`) with research-backed sampler, scheduler, steps, and CFG values for 10+ model families. User overrides in `model-settings.user.jsonc` (auto-created from template on install, gitignored).\n\n---\n\n## Examples\n\n### Generate an image\n\n```\n\u003e /comfy:gen a cyberpunk city at night with neon lights\n```\n\nClaude will:\n1. Check installed checkpoints (download one if needed)\n2. Build a txt2img workflow with your prompt\n3. Execute it on ComfyUI\n4. Return the generated image\n\n### Visualize a workflow\n\n```\n\u003e /comfy:viz ~/workflows/my-workflow.json\n```\n\nProduces a Mermaid diagram with nodes grouped by category:\n\n```mermaid\nflowchart LR\n  subgraph Loaders\n    1[\"CheckpointLoaderSimple\"]\n  end\n  subgraph Conditioning\n    2([\"Positive Prompt\"])\n    3([\"Negative Prompt\"])\n  end\n  subgraph Sampling\n    5{{\"KSampler\u003cbr/\u003esteps:20 cfg:8\"}}\n  end\n  1 --\u003e|MODEL| 5\n  2 --\u003e|CONDITIONING| 5\n  3 --\u003e|CONDITIONING| 5\n```\n\n### Debug a failed workflow\n\n```\n\u003e /comfy:debug\n```\n\nAutomatically reads the last execution history and logs, identifies the failing node, checks for missing models or node packs, and suggests a fix.\n\n```\n\u003e /comfy:debug abc123-def456\n```\n\nDiagnose a specific execution by prompt ID.\n\n### Parameter sweep\n\n```\n\u003e /comfy:batch a cat in a field, cfg:5-10:2, sampler:euler,dpmpp_2m\n```\n\nGenerates a grid of images across all parameter combinations and presents a summary table with results.\n\nSupported sweep parameters: `cfg`, `steps`, `sampler`, `scheduler`, `seed`, `denoise`, `width`, `height`.\n\n### Multi-step recipes\n\n```\n\u003e /comfy:recipe hires-fix a dramatic fantasy landscape with castles\n```\n\nRuns a two-pass pipeline: txt2img at 512x768, then img2img upscale to 1024x1536 with detail enhancement.\n\nAvailable recipes:\n\n| Recipe | Description |\n|--------|-------------|\n| `portrait` | Generate at 1024x1024, then 2x upscale to 2048x2048 |\n| `hires-fix` | Low-res generation → img2img upscale with denoise 0.4-0.5 |\n| `style-transfer` | Apply a style prompt to an existing image via img2img |\n| `product-shot` | Product image with clean white background |\n\n### Convert workflow format\n\n```\n\u003e /comfy:convert ~/workflows/my-ui-workflow.json\n```\n\nConverts between ComfyUI's UI format (nodes + links arrays) and API format (node IDs → {class_type, inputs}).\n\n### Install a custom node pack\n\n```\n\u003e /comfy:install comfyui-impact-pack\n```\n\nSearches the registry, shows details, clones the repo to `custom_nodes/`, installs dependencies, and offers to restart ComfyUI.\n\n### Browse output gallery\n\n```\n\u003e /comfy:gallery last 5\n\u003e /comfy:gallery today\n```\n\nLists recent outputs with embedded metadata — shows checkpoint, prompt, seed, steps, CFG, sampler for each image.\n\n### Compare workflows\n\n```\n\u003e /comfy:compare workflow-a.json vs workflow-b.json\n```\n\nShows added/removed nodes, changed parameters (old → new values), and optional Mermaid diagrams for visual comparison.\n\n### Validate before running\n\n```\n\u003e Validate this workflow before I run it\n```\n\nChecks for missing node types, broken connections, invalid output indices, and missing model files — without executing.\n\n### Manage models\n\n```\n\u003e What checkpoints do I have installed?\n\u003e Search HuggingFace for SDXL turbo models\n\u003e Download this model to my checkpoints folder\n```\n\n### Manage VRAM\n\n```\n\u003e Free my VRAM\n\u003e What embeddings do I have?\n```\n\n### Extract workflow from an image\n\n```\n\u003e Extract the workflow from this image: ~/outputs/ComfyUI_00042_.png\n```\n\nReads the PNG metadata chunks to recover the exact workflow and prompt used to generate the image.\n\n### Explore custom nodes\n\n```\n\u003e /comfy:node-skill comfyui-impact-pack\n```\n\nGenerates a comprehensive skill file documenting every node, its inputs/outputs, and usage patterns.\n\n### Process control\n\n```\n\u003e Restart ComfyUI\n\u003e Stop ComfyUI\n\u003e Start ComfyUI back up\n```\n\n---\n\n## Configuration\n\nThe server auto-detects your ComfyUI installation and port. Override with environment variables if needed:\n\n### Deployment modes\n\n`comfyui-mcp` operates in one of three modes, auto-selected from the environment:\n\n| Mode | Trigger | Local FS / process tools? |\n|------|---------|----------------------------|\n| **Local** | default | yes |\n| **Remote** | `--comfyui-url` / `COMFYUI_URL` points at a non-loopback host | no — server skips `COMFYUI_PATH` auto-detection so stale local installs can't silently absorb uploads |\n| **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` |\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `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**. |\n| `COMFYUI_HOST` | `127.0.0.1` | ComfyUI server address |\n| `COMFYUI_PORT` | *(auto-detect)* | ComfyUI server port (tries 8188, then 8000) |\n| `COMFYUI_PATH` | *(auto-detect)* | Path to ComfyUI data directory. Auto-detection suppressed in remote/cloud modes. |\n| `COMFYUI_API_KEY` | | Comfy Cloud API key. When set, **cloud mode** is active and the server talks to `cloud.comfy.org`. Never logged. |\n| `COMFYUI_CLOUD_URL` | `https://cloud.comfy.org` | Override the Comfy Cloud endpoint (testing/staging). |\n| `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. |\n| `COMFYUI_AUTH_HEADER` | `Authorization` | Header name for `COMFYUI_AUTH_TOKEN` (e.g. `X-API-Key`). |\n| `COMFYUI_AUTH_SCHEME` | `Bearer` for `Authorization`, else none | Scheme prefix on the token value (e.g. `Bearer`, `Token`). |\n| `CIVITAI_API_TOKEN` | | CivitAI API token for model downloads |\n| `HUGGINGFACE_TOKEN` | | HuggingFace token for higher API rate limits |\n| `GITHUB_TOKEN` | | GitHub token for skill generation (avoids rate limits) |\n| `REGISTRY_ACCESS_TOKEN` | | Comfy Registry API key for `publish_custom_node` (env-only, never logged) |\n| `COMFYUI_DOWNLOAD_CACHE_DIR` | `~/.comfyui-mcp/cache` | Content-addressed model-download cache (dedup + concurrent coalescing) |\n| `COMFYUI_LRU_CACHE_SIZE_GB` | `0` | Cap the download cache in GB; `0` disables LRU eviction |\n| `COMFYUI_STARTUP_CHECK_INTERVAL_S` / `…_MAX_TRIES` | `1` / `20` | Readiness-probe interval + max tries when starting a local ComfyUI |\n| `COMFYUI_ALWAYS_RESTART` | `false` | Auto-restart a crashed local ComfyUI (bounded by `COMFYUI_RESTART_MAX_ATTEMPTS` / `COMFYUI_RESTART_WINDOW_S`) |\n| `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) |\n| `COMFYUI_MCP_INTERRUPT_S` | `30` | Seconds `cancel_job` waits for an interrupt to actually stop a job before escalating to `/free` and reporting it wedged |\n| `LOG_LEVEL` | `info` | Logging verbosity: `debug`, `info`, `warn`, `error` |\n\n### Transports\n\nThe server speaks **stdio by default** (what Claude Code, Claude Desktop, and the MCP Inspector expect — no flags needed). For MCP gateways, remote/hosted setups, or `fetch`-based clients, opt into **streamable-HTTP**:\n\n```bash\n# stdio (default)\nnpx -y comfyui-mcp\n\n# streamable-HTTP on http://127.0.0.1:9100/mcp\nnpx -y comfyui-mcp --http\nnpx -y comfyui-mcp --http --host 0.0.0.0 --port 9100   # bind/port overrides\n```\n\n| Flag | Env | Default | Description |\n|------|-----|---------|-------------|\n| `--http` / `--transport http` | `MCP_TRANSPORT=http` | `stdio` | Serve streamable-HTTP at `/mcp` instead of stdio |\n| `--host \u003ch\u003e` | `MCP_HOST` | `127.0.0.1` | HTTP bind host (use `0.0.0.0` to expose) |\n| `--port \u003cn\u003e` | `MCP_PORT` | `9100` | HTTP port |\n| `--comfyui-url \u003curl\u003e` | `COMFYUI_URL` | *(auto-detect)* | Target a specific (incl. remote) ComfyUI |\n\n### Remote ComfyUI\n\nPoint the server at a ComfyUI running anywhere — no local install required:\n\n```bash\nnpx -y comfyui-mcp --comfyui-url http://192.168.1.50:8188\nnpx -y comfyui-mcp --http --comfyui-url https://comfy.example.com:8443\n```\n\n**Behind a reverse proxy / API gateway** (path prefix + auth header) — for a\nself-hosted ComfyUI exposed under a prefixed route with its own auth layer (this\nis *not* Comfy Cloud, which is `COMFYUI_API_KEY`):\n\n```bash\nCOMFYUI_URL=https://gateway.example.com/comfyapi \\\nCOMFYUI_AUTH_TOKEN=your-token \\\n  npx -y comfyui-mcp --http        # → Authorization: Bearer your-token, requests under /comfyapi\n\n# custom header / scheme:\nCOMFYUI_URL=https://gateway.example.com/comfyapi \\\nCOMFYUI_AUTH_HEADER=X-API-Key COMFYUI_AUTH_TOKEN=your-token \\\n  npx -y comfyui-mcp --http        # → X-API-Key: your-token\n```\n\n### Auto-detection\n\n**Port**: Probes `8188` (CLI default) then `8000` (Desktop app default) via `/system_stats`.\n\n**Path**: Checks common locations in order:\n\n- `~/Documents/ComfyUI` (macOS/Windows Desktop app data directory)\n- `~/Library/Application Support/ComfyUI` (macOS)\n- `~/AppData/Local/Programs/ComfyUI/resources/ComfyUI` (Windows Desktop app install)\n- `~/AppData/Local/ComfyUI` (Windows)\n- `~/ComfyUI`, `~/code/ComfyUI`, `~/projects/ComfyUI`, `~/src/ComfyUI`\n- `/opt/ComfyUI`, `~/.local/share/ComfyUI` (Linux)\n- Scans `~/Documents` and `~/My Documents` for any directory containing \"ComfyUI\"\n\nSet `COMFYUI_PATH` to skip detection and use an explicit path.\n\n---\n\n## How It Works\n\nThe server communicates with ComfyUI through its REST API and WebSocket interface:\n\n- **WebSocket** — enqueue workflows, receive real-time progress updates (step-by-step via background monitor script), get execution results\n- **REST API** — system stats, node definitions (`/object_info`), logs, history, queue management, workflow library, VRAM control (`/free`), embeddings\n- **File system** — read/write models directory, detect installation paths, upload images, extract PNG metadata, browse outputs\n- **External APIs** — HuggingFace (model search), ComfyUI Registry (custom node discovery), GitHub (skill generation), CivitAI (model downloads)\n\nAll communication with the MCP client (Claude Code) happens over **stdio** using the [Model Context Protocol](https://modelcontextprotocol.io). Logs go to stderr to avoid polluting the protocol stream.\n\n---\n\n## Development\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org) \u003e= 22.0.0\n- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) running locally\n\n### Setup\n\n```bash\ngit clone https://github.com/artokun/comfyui-mcp.git\ncd comfyui-mcp\nnpm install\n```\n\n### Scripts\n\n| Script | Description |\n|--------|-------------|\n| `npm run dev` | Run from source with tsx (hot reload) |\n| `npm run build` | Compile TypeScript to `dist/` |\n| `npm start` | Run compiled output |\n| `npm test` | Run unit tests (vitest) |\n| `npm run test:integration` | Run integration tests (requires running ComfyUI) |\n| `npm run lint` | Type-check without emitting |\n| `npm run generations:stats` | Show local generation tracking statistics |\n| `npm run sync-agents` | Sync Claude skills/commands/hooks to Google Antigravity, OpenCode, and other AI IDE formats that supports .agents files |\n\n### Local testing with Claude Code\n\nPoint Claude Code at your local build instead of the npm package:\n\n```json\n{\n  \"mcpServers\": {\n    \"comfyui\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/comfyui-mcp/dist/index.js\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\nOr test the plugin directly:\n\n```bash\nclaude --plugin-dir ./plugin\n```\n\n### Project structure\n\n```\nmodel-settings.json            # Community-maintained model presets (shipped)\nmodel-settings.user.jsonc.example  # User override template (copied on install)\nscripts/\n  postinstall.mjs              # Auto-creates user config from template\n  generation-stats.mjs         # CLI: npm run generations:stats\nsrc/\n  index.ts                 # MCP server entry point (stdio transport)\n  config.ts                # Auto-detection \u0026 environment config\n  comfyui/\n    client.ts              # ComfyUI WebSocket/HTTP client wrapper\n    types.ts               # TypeScript interfaces\n  services/\n    workflow-executor.ts   # Execute workflows, handle images \u0026 errors\n    workflow-composer.ts   # Templates (txt2img, img2img, upscale, inpaint)\n    workflow-validator.ts  # Dry-run validation (missing nodes, models, connections)\n    image-management.ts    # Upload images, extract PNG metadata, list outputs\n    mermaid-converter.ts   # Workflow → Mermaid diagram\n    workflow-converter.ts  # UI → API: de-virtualize Get/Set buses + Reroutes, expand subgraphs, resolve bypass (powers strip_workflow)\n    workflow-slicer.ts     # sliceWorkflow() — rgthree Fast-Groups-Bypass pipeline un-chunker (shared by the CLI + slice_workflow)\n    mermaid-parser.ts      # Mermaid diagram → Workflow\n    model-resolver.ts      # HuggingFace search, local models, downloads\n    generation-tracker.ts  # SQLite generation log, settings dedup, stats\n    file-hasher.ts         # SHA256 hashing of .safetensors with cache\n    civitai-lookup.ts      # CivitAI API lookup by content hash\n    workflow-settings-extractor.ts  # Extract settings from workflow JSON\n    process-control.ts     # Stop, start, restart ComfyUI process\n    registry-client.ts     # ComfyUI Registry API\n    skill-generator.ts     # Generate node pack skill docs\n  tools/                   # MCP tool registration (one file per group)\n    workflow-execute.ts    # enqueue_workflow, get_system_stats\n    workflow-visualize.ts  # visualize_workflow, mermaid_to_workflow\n    workflow-compose.ts    # create_workflow, modify_workflow, get_node_info\n    workflow-validate.ts   # validate_workflow\n    workflow-library.ts    # list_workflows, get_workflow, strip_workflow, slice_workflow, save_workflow\n    image-management.ts    # upload_image, workflow_from_image, list_output_images\n    model-management.ts    # search_models, download_model, list_local_models\n    memory-management.ts   # clear_vram, get_embeddings\n    registry-search.ts     # search_custom_nodes, get_node_pack_details\n    skill-generator.ts     # generate_node_skill\n    generation-tracker.ts  # suggest_settings, generation_stats\n    diagnostics.ts         # get_logs, get_history\n    process-control.ts     # stop_comfyui, start_comfyui, restart_comfyui\n    index.ts               # Registers all tool groups\n  utils/\n    errors.ts              # Custom error hierarchy with MCP integration\n    logger.ts              # stderr-only logging (safe for stdio transport)\n    image.ts               # Base64 encoding utilities\nplugin/\n  .claude-plugin/          # Plugin manifest\n  .mcp.json                # MCP server config for plugin\n  commands/                # Slash commands\n    gen.md                 # /comfy:gen — image generation\n    viz.md                 # /comfy:viz — workflow visualization\n    node-skill.md          # /comfy:node-skill — skill generation\n    debug.md               # /comfy:debug — failure diagnosis\n    batch.md               # /comfy:batch — parameter sweeps\n    convert.md             # /comfy:convert — format conversion\n    install.md             # /comfy:install — node pack installation\n    gallery.md             # /comfy:gallery — output browser\n    compare.md             # /comfy:compare — workflow diff\n    recipe.md              # /comfy:recipe — multi-step pipelines\n  skills/                  # Knowledge bases\n    comfyui-core/          # Workflow format, node types, pipeline patterns\n    prompt-engineering/    # CLIP syntax, model-specific prompting\n    troubleshooting/       # Error catalog with patterns and fixes\n    model-compatibility/   # Compatibility matrix per model family\n  agents/                  # Autonomous agents\n    explorer.md            # Research custom node packs, generate skills\n    debugger.md            # Diagnose workflow failures\n    optimizer.md           # Analyze and optimize workflows\n  hooks/                   # Pre/post tool-use hooks\n    hooks.json             # Hook configuration\n    vram-check.mjs         # VRAM watchdog before execution\n    save-warning.mjs       # Save prompt before stop/restart\n    job-complete-notify.mjs # Job completion notification via temp files\n  scripts/                 # Background scripts\n    monitor-progress.mjs   # Real-time WebSocket progress monitor\n```\n\n---\n\n## Troubleshooting\n\n**\"ComfyUI not detected on ports 8188, 8000\"**\nMake 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.\n\n**\"COMFYUI_PATH is not configured\"**\nThe auto-detection couldn't find your ComfyUI data directory. Set `COMFYUI_PATH` to the directory containing your `models/` folder (e.g., `~/Documents/ComfyUI`).\n\n**\"Multiple ComfyUI installations detected\"**\nThis is informational — the server uses the first one found. Set `COMFYUI_PATH` to pick a specific installation.\n\n**Model downloads fail**\nFor HuggingFace gated models, set `HUGGINGFACE_TOKEN`. For CivitAI, set `CIVITAI_API_TOKEN`.\n\n**Workflow execution errors**\nUse `/comfy:debug` to automatically diagnose failures. Or use `get_history` / `get_logs` directly to see detailed error messages including Python tracebacks from ComfyUI.\n\n**Out of memory (OOM)**\nUse `clear_vram` to free GPU memory before running large workflows. The VRAM watchdog hook will warn you automatically if memory is critically low. See the **troubleshooting** skill for model-specific VRAM estimates.\n\n**Missing custom nodes**\nUse `/comfy:install \u003cpack\u003e` to install missing node packs from the registry. The debug command will detect and suggest missing packs automatically.\n\n---\n\n## Contributing\n\nContributions are welcome! See **[CONTRIBUTING.md](./CONTRIBUTING.md)** for the dev setup, project\nconventions, how to add an MCP tool, and the release process.\n\nQuick version: fork → branch (`feat/my-feature`) → make changes (ensure `npm run build` and\n`npm test` pass; run `npm run docs:gen` if you touched tools) → open a PR.\n\n---\n\n## Maintainer\n\nBuilt and maintained by [**@artokun**](https://github.com/artokun) — a regular contributor across the Comfy-Org ecosystem:\n\n- **[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`.\n- **[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)).\n\n**Comfy-Org folks** (or anyone hiring around the ComfyUI ecosystem): I'd genuinely love to chat — **[art.longbottom.jr@gmail.com](mailto:art.longbottom.jr@gmail.com)**.\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE) for details.\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md) for the full, structured release history.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartokun%2Fcomfyui-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fartokun%2Fcomfyui-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartokun%2Fcomfyui-mcp/lists"}