> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Install & Environment
> Install/update ComfyUI and the sidebar panel, self-update the MCP server, apply a setup manifest, manage workspaces, inspect the environment, configure ComfyUI-Manager, report issues.
4 tools. Generated from the live MCP tool schemas — do not edit by hand; run `npm run docs:gen`.
**You don't type these calls.** Ask your agent for what you want in ordinary English — it chooses the tool and fills in the arguments. The JSON on this page is what it sends. New here? Start with [Using the tools](/docs/using-tools).
## install\_comfyui
Install, update and configure the local ComfyUI installation, its sidebar panel, and this MCP server itself. Driven by the `action` parameter:
* action:"install" — Install ComfyUI locally: git-clone it into `target_path`, create a dedicated workspace virtualenv (\/.venv), and install Python requirements INTO that venv (never the Python running this MCP server) via pip or uv. ComfyUI-Manager is installed from manager\_requirements.txt when present, else git-cloned as a fallback. Mirrors `comfy-cli install`. LOCAL, subprocess-only and independent of any remote --comfyui-url target; the target dir must be empty or non-existent (an existing install is never overwritten). Runs SYNCHRONOUSLY and can take several minutes (large git clone + full torch/dependency install); the call blocks until done. On success returns a JSON report \{ installed, targetPath, venvPath, comfyuiUrl, managerInstalled, managerVia, version, pythonInstaller, steps\[] }. Does NOT start ComfyUI. `target_path` is REQUIRED.
* action:"update" — Update the ComfyUI CORE install: runs `git pull` in the configured ComfyUI directory and reinstalls its Python requirements (auto-detecting uv vs pip). Requires a local install (COMFYUI\_PATH); returns a clear error when targeting a remote instance via --comfyui-url. The requirements install targets the running server's own interpreter (recorded when this server launched ComfyUI, or an explicit COMFYUI\_PYTHON); when that interpreter cannot be verified the update refuses rather than install into a guessed environment — start ComfyUI or connect first. Does NOT touch custom nodes.
* action:"update\_all" — Update ALL installed CUSTOM NODES via the ComfyUI-Manager HTTP API. Mirrors `comfy-cli update all`. This does NOT update ComfyUI core — use action:"update" for that. Works against the connected instance (local or remote); updates run asynchronously and a ComfyUI restart may be required afterward. REFUSED while the comfyui-mcp sidebar panel is version-pinned, because 'all' would move the pinned panel too and ComfyUI-Manager cannot update everything-except-one-pack — clear the pin with action:"panel" + panel\_action:"unpin", or update the other packs individually by id.
* action:"panel" — Install, update, reinstall, sync, pin, unpin, unlock, or report status of the ComfyUI sidebar panel ('comfyui-agent-panel' on the Comfy Registry; repo comfyui-mcp-panel) in the LOCAL ComfyUI's custom\_nodes, selected by `panel_action` (default "status"). Uses the same ComfyUI-Manager path as install\_custom\_node and always targets the 'nightly' (git-HEAD) channel. Local-only (no-op/refuses in remote/cloud mode) and NEVER modifies a dev install (a symlinked panel dir). After install/update/reinstall/sync, ComfyUI must be RESTARTED to load the new/updated node — this tool does not auto-restart. The panel is also auto-installed-if-missing when the MCP server loads. A version PIN (panel\_action:"pin") holds the panel where it is: while a pin is set, install/update/reinstall/sync and the auto-install all refuse, and 'sync' only warns that a newer panel exists. Panel operations are serialized across orchestrator processes by a lock file that is never auto-reclaimed — if a crashed orchestrator wedges it, panel\_action:"unlock" reclaims the lock once it is provably abandoned. This is the SIDEBAR PANEL only; it never touches ComfyUI core or this npm package.
* action:"self\_update" — Check or apply a self-update of the comfyui-mcp NPM PACKAGE (this MCP server), selected by `self_update_action` (default "status"). The server also auto-checks on start (opt out with COMFYUI\_MCP\_AUTOUPDATE=0). Detects the install mode: a dev install (npm link / source checkout) is NEVER updated; global/local installs are updated via npm; npx fetches latest on next run. The running process cannot hot-swap its own code — after an update you must RECONNECT (/mcp) or restart the orchestrator to load the new version. This tool does not auto-restart. On Windows the running orchestrator holds its own sharp DLL locked, so an in-place npm replace fails (EBUSY); the update is then handed to a deferred helper that finishes it once the orchestrator has fully stopped, and the new version loads at the next start. A failed update reports npm's own error output. This updates comfyui-mcp ITSELF — not ComfyUI (action:"update"), not the sidebar panel (action:"panel"), and not custom nodes (install\_comfyui (action:"update\_all")).
* action:"environment" — Report ComfyUI environment info (mirrors `comfy-cli env`): the running instance details from /system\_stats (OS, Python, ComfyUI version, GPU/VRAM — works for remote targets) plus local probes when a workspace path is available (Python version, git revision, ComfyUI-Manager version, and key pip packages like torch/CUDA). The local python probe targets the interpreter the RUNNING server uses (its venv / embedded / standalone python, resolved from the live server), never a bare `python` on PATH. Degrades gracefully and NEVER guesses: when the correct interpreter can't be confirmed, `local.python_probe_trusted` is false, `local.packages` is omitted, and `local.python_probe_reason` says why — an absent package list means UNDETERMINED, never 'not installed'. READ-ONLY.
* action:"configure\_manager" — Configure ComfyUI-Manager settings, mirroring `comfy-cli manager` subcommands; `manager_setting` picks which setting and `value` its new value. Most settings use the ComfyUI-Manager HTTP API (works against remote ComfyUI); set\_network\_mode and set\_security\_level have no HTTP setter and are written to Manager's config.ini (requires a known local ComfyUI path; restart ComfyUI to apply).
**In plain terms:** One tool for everything that INSTALLS or UPDATES: ComfyUI itself, every custom node pack, the Agent sidebar panel, this MCP server, and ComfyUI-Manager's own settings. `action` picks which — and nothing here is read-only except action:"environment" and the two "status" sub-actions.
### Parameters
Which install/environment operation to perform. action:"update", action:"update\_all" and action:"environment" take no other parameters; action:"install" requires `target_path`; action:"panel" takes `panel_action` (+ `version`/`reason` for a pin); action:"self\_update" takes `self_update_action`; action:"configure\_manager" requires `manager_setting` (+ `value`).
Options: `action:"install"`, `action:"update"`, `action:"update_all"`, `action:"panel"`, `action:"self_update"`, `action:"environment"`, `action:"configure_manager"`.
action:"install" — REQUIRED absolute path to the workspace directory to install ComfyUI into. Must be empty or non-existent.
action:"install" — if true, do not clone/install ComfyUI-Manager. Default false (Manager is installed).
action:"install" — if true, prefer `uv pip install` over plain pip when uv is available on PATH. Falls back to pip if uv is missing. Default false.
action:"install" — ComfyUI version to install (comfy-cli semantics): "nightly" (default-branch HEAD), "latest" (newest release tag), or a semantic version like "0.3.40" (checked out as tag v0.3.40). Raw git refs/branches are rejected. Omit to track the default branch HEAD. ALSO used by action:"panel" + panel\_action:"pin", where it is the PANEL version to hold at, e.g. '0.11.20' (take it from the installedVersion that panel\_action:"status" reports).
action:"panel" — which sidebar-panel operation to run. status: report installed/version/dev-symlink/pin plus a sync assessment (never errors). sync: bring the panel up to what this orchestrator needs — no-ops when already current, WARNS ONLY when pinned, and reports the version re-read from disk afterwards. install: add the panel (nightly). update: pull the latest nightly. Works on either install shape — a git checkout is fast-forwarded, and a Comfy Registry ZIP install (which has no .git) is replaced with a verified fresh clone, keeping the previous copy outside custom\_nodes. Success is always re-read from disk. reinstall: uninstall + reinstall (nightly). pin: hold the panel at a version (requires `version`). unpin: clear the pin so a sync can proceed. unlock: recover from a crashed/killed orchestrator's leftover panel operation lock — reclaims it ONLY when it is provably abandoned (older than the stale threshold AND its recorded owner process is dead), and refuses with the observed state otherwise. install/update/reinstall/sync refuse on a dev symlink or an active pin, and require a local workspace (COMFYUI\_PATH or the saved default workspace).
Options: `status`, `install`, `update`, `reinstall`, `sync`, `pin`, `unpin`, `unlock`.
action:"panel" + panel\_action:"pin" only: why the user is pinning (stored with the pin).
action:"self\_update" — status: report install mode + current vs latest version + dev-link note (never errors). update: update to the latest published version (refuses on a dev link; no-op when already up to date or for npx).
Options: `status`, `update`.
action:"configure\_manager" — REQUIRED. Which ComfyUI-Manager setting to change. HTTP API: set\_preview\_method, set\_db\_mode, set\_component\_policy, set\_update\_policy, set\_channel, reset\_queue. config.ini fallback: set\_network\_mode, set\_security\_level.
Options: `set_preview_method`, `set_db_mode`, `set_component_policy`, `set_update_policy`, `set_channel`, `reset_queue`, `set_network_mode`, `set_security_level`.
action:"configure\_manager" — value for the chosen `manager_setting` (omit only for reset\_queue). Allowed values per setting — set\_preview\_method: auto | latent2rgb | taesd | none; set\_db\_mode: local | cache | remote; set\_component\_policy: workflow | higher | mine; set\_update\_policy: stable-comfyui | nightly-comfyui; set\_channel: a channel name (e.g. default); set\_network\_mode: public | private | offline; set\_security\_level: strong | normal | normal- | weak. HTTP-API settings take effect live; the config.ini ones (set\_network\_mode, set\_security\_level) apply only after a ComfyUI restart.
### Examples
**You say:** Tell me about my setup — useful when I'm reporting a bug.
```json theme={null}
{
"tool": "install_comfyui",
"arguments": {
"action": "environment"
}
}
```
**You get back:** Where ComfyUI is installed, the Python and torch versions, the GPU, and which settings are in force. The first thing to paste into an issue.
**You say:** What version of the panel have I got?
```json theme={null}
{
"tool": "install_comfyui",
"arguments": {
"action": "panel",
"panel_action": "status"
}
}
```
**You get back:** The installed panel version, where it lives, and whether it is pinned. This changes nothing.
**You say:** It says my panel is too old — update it.
```json theme={null}
{
"tool": "install_comfyui",
"arguments": {
"action": "panel",
"panel_action": "update"
}
}
```
**You get back:** The update result. Two more steps are yours: restart ComfyUI, then hard-refresh the ComfyUI browser tab (Ctrl+Shift+R). Without that refresh the tab keeps running the old cached panel code and the same refusal comes back.
**You say:** Am I on the latest comfyui-mcp?
```json theme={null}
{
"tool": "install_comfyui",
"arguments": {
"action": "self_update",
"self_update_action": "status"
}
}
```
**You get back:** Your version, the latest published version, and whether they differ.
**You say:** Update comfyui-mcp itself.
```json theme={null}
{
"tool": "install_comfyui",
"arguments": {
"action": "self_update",
"self_update_action": "update"
}
}
```
**You get back:** The upgrade result. Your MCP client has to be restarted afterwards to pick up the new server.
This updates THIS server, not ComfyUI and not the sidebar panel — those are action:"update" and action:"panel".
**You say:** Update every custom node I have installed.
```json theme={null}
{
"tool": "install_comfyui",
"arguments": {
"action": "update_all"
}
}
```
**You get back:** Confirmation that the bulk update was queued with ComfyUI-Manager. It runs asynchronously and ComfyUI usually needs a restart after.
This moves EVERY installed pack, not just the one that is broken. It is refused while the sidebar panel is version-pinned.
***
## apply\_manifest
Apply a ComfyUI setup manifest from an inline object or .json/.yaml/.yml file. Composes custom-node installs and model downloads, installs pip packages, and reports apt entries as skipped (system packages need manual/root installation). LOCAL ComfyUI (COMFYUI\_PATH set): nodes/models land on the local filesystem and pip installs into the ComfyUI Python env. REMOTE ComfyUI: custom\_nodes and models are routed through the ComfyUI-Manager HTTP API (handled on the host), while pip and apt entries are reported as skipped (no remote equivalent). Each item reports applied/skipped/failed independently.
### Parameters
Inline manifest object. Provide exactly one of `manifest` or `path`.
Path to a .json, .yaml, or .yml manifest file. Provide exactly one of `manifest` or `path`.
### Example
No worked example yet — the call below is a skeleton generated from the required parameters. Real examples live in `scripts/tool-doc-examples.ts`; contributions welcome.
```json theme={null}
{
"tool": "apply_manifest",
"arguments": {}
}
```
***
## workspace
Inspect and manage ComfyUI workspaces (local installs). Driven by the `action` parameter:
* action:"get" — Report the active ComfyUI workspace (mirrors `comfy-cli which`): the local installation path being used (from COMFYUI\_PATH or auto-detection), the source of that path, any persisted default workspace, and the resolved API target the MCP server talks to.
* action:"set\_default" — Persist a default ComfyUI workspace path to the MCP config file (mirrors `comfy-cli set-default`). The value is stored under the OS config dir (e.g. \~/.config/comfyui-mcp/workspace.json) and reported by action:"get"/action:"list". Does NOT change the live API target. `path` is REQUIRED, e.g. \{action:"set\_default", path:"/opt/ComfyUI"}.
* action:"list" — List known/auto-detected ComfyUI installations on this machine. Scans common install locations across macOS, Linux, and Windows and marks which one is active and which is the saved default.
**In plain terms:** Which ComfyUI installation everything else is talking about. One tool, three jobs, chosen with `action` — this is the tool the [consolidation note](/docs/using-tools#one-tool-several-jobs) uses as its worked example.
### Parameters
Which workspace operation to perform. "get" and "list" take no other parameters; "set\_default" requires `path`.
Options: `action:"get"`, `action:"set_default"`, `action:"list"`.
action:"set\_default" — REQUIRED absolute path to a ComfyUI installation directory to remember as the default workspace.
### Examples
**You say:** Which ComfyUI am I actually using?
```json theme={null}
{
"tool": "workspace",
"arguments": {
"action": "get"
}
}
```
**You get back:** The active install's path and how it was chosen — a flag, an environment variable, or the saved default.
**You say:** Always use the one on my big drive from now on.
```json theme={null}
{
"tool": "workspace",
"arguments": {
"action": "set_default",
"path": "D:/AI/ComfyUI"
}
}
```
**You get back:** Confirmation, and it sticks across restarts. Later sessions target this install unless something overrides it.
***
## report\_issue
File or triage a GitHub issue for a bug/problem you hit (ComfyUI, a workflow, a model, custom nodes, or comfyui-mcp/its panel). For OUR repos (artokun/comfyui-mcp, artokun/comfyui-mcp-panel) it sends the report to the AI triage worker, which searches existing OPEN and CLOSED issues, version-matches, and either files a new issue, adds context to an existing one, or — if the problem was already FIXED in a newer version than the user runs — answers with the fixing PR + fixed-in version and a recommendation to upgrade (no new issue). It returns that triage result plus an instant check of whether the user is on the latest versions. TIMING: this call BLOCKS while the triage runs — typically a few minutes — and that wait is normal, not a hang. It always returns eventually (every request is time-capped and the poll budget is bounded); on a failing network the caps make that wait longer, but never indefinite. Do not abort a slow call just to retry it: once the worker has accepted the report it keeps triaging on its own — filing, deduping into an existing issue, advising an upgrade, or (rarely) reporting that it could not file — so a blind retry can double-file. If triage outlasts the polling budget the call still returns, with pending:true (and a job\_id when the worker gave one — an accepted submit whose acknowledgement was unreadable returns pending without it). If the worker is unreachable it falls back to a prefilled GitHub 'new issue' URL. For third-party repos it returns a prefilled URL to SHARE (it does not auto-file). ALWAYS pass mcp\_version and panel\_version from the known environment (the env line in your context, e.g. 'mcp=… panel=…') so the worker can tell the user if simply upgrading fixes it — the single most common resolution. Surface the worker's agent\_message / upgrade advice to the user.
### Parameters
Short, specific issue title.
Issue body: what happened, steps to reproduce, the exact error text, and environment (GPU/VRAM, ComfyUI version, ComfyUI FRONTEND version, OS) if known. The FRONTEND version is a SEPARATE package from ComfyUI and they move independently — get\_system\_stats (action:"health") prints both, and for any panel/UI bug it is often the deciding variable. Scrub secrets first.
owner/repo (default 'artokun/comfyui-mcp'; use 'artokun/comfyui-mcp-panel' for the sidebar panel).
Optional GitHub label names to prefill.
The running comfyui-mcp version (from the env line in your context). Auto-detected if omitted.
The running comfyui-mcp-panel (sidebar) version, from the env line in your context, if known.
Force the prefilled-URL path even for our repos (skip the Worker). Rarely needed.
### Example
**You say:** This keeps crashing. File a bug about it.
```json theme={null}
{
"tool": "report_issue",
"arguments": {
"title": "Video render finishes but no file appears in outputs",
"body": "Running the WAN template completes and history shows success, but output/video/ is empty. Happens every time on 0.49.3."
}
}
```
**You get back:** A GitHub issue on the project, with your environment details attached automatically, and a link to it.
This posts publicly. The environment block it attaches includes paths and versions from your machine — glance at what it drafted before agreeing to send it.
***