mcp-comfyui-proxy
v0.3.4
Published
Local HTTP MCP with isolated ComfyUI reverse-proxy sessions
Readme
ComfyUI MCP Proxy
Available on npm, with release notes on GitHub.
Control ComfyUI workflows through MCP and a local reverse proxy. The proxy opens ComfyUI in your browser and connects its workflow tabs to your MCP client.
Requires Node.js 24.12 or later with npm and access to a ComfyUI backend.
Start through npx
npx -y --prefer-online mcp-comfyui-proxy@latest mcpA typical MCP client configuration is:
{
"mcpServers": {
"comfyui": {
"command": "npx",
"args": ["-y", "--prefer-online", "mcp-comfyui-proxy@latest", "mcp"]
}
}
}For Codex:
[mcp_servers.comfyui]
command = "npx"
args = ["-y", "--prefer-online", "mcp-comfyui-proxy@latest", "mcp"]
startup_timeout_sec = 120
tool_timeout_sec = 180Set the MCP client's tool-call timeout to 180 seconds to allow longer file transfers. Calls return as soon as the operation finishes.
The local proxy starts automatically on the first tool call and runs in the background.
Connect and edit
Tool-call examples use JavaScript object notation. Every file must be an absolute path on the MCP machine; Windows paths such as C:/work/workflow.json are also supported.
connect({ url: "http://127.0.0.1:8188/" })
status({ session_id: "<session_id>" })
// Select an id from workflows_opened.
workflow_download({ id: "<workflow_id>", file: "/absolute/path/workflow.json" })
// Edit the local standard ComfyUI Workflow JSON, then:
workflow_upload({ id: "<workflow_id>", file: "/absolute/path/workflow.json" })
workflow_save({ id: "<workflow_id>" })
run({ id: "<workflow_id>" })
backend_status({ session_id: "<session_id>" })connect probes reachability, creates an isolated proxy and opens its URL in your default browser. A login page, redirect, 401 or 403 counts as reachable. Log in through the proxied page when required. The injected bridge reports open workflow tabs and displays a connection banner with the real backend URL.
session_id selects a backend and its stored authentication. Workflow id selects one exact internal editor tab across browser tabs and windows. Obtain IDs from the responses; do not derive them from names or UUIDs. workflow_uuid is metadata for correlating executions, not an editor routing ID.
Reading or modifying a workflow activates its internal tab. Creating or opening a workflow uses the last focused connected browser page, or the first connected page if no focus was reported. It does not switch operating-system windows or browser tabs.
Tools
The CLI supplies descriptions and JSON Schemas from one shared definition module.
| Tool | Purpose |
|---|---|
| connect | Probe a backend, create a proxy session and open the browser. |
| status | List sessions and open workflow tabs, with diagnostic log paths. |
| disconnect | Close one proxy session without stopping ComfyUI. |
| backend_status | Jobs accepted through proxy sessions, including UI runs. |
| backend_history | All backend jobs, including runs outside proxy sessions. |
| backend_node_info | Search node types or read one native object_info definition. |
| backend_inputs_list | Return the backend input list and its reported root scope. |
| backend_workflow_list | List saved workflow files recursively, without downloading graphs. |
| backend_upload | Upload a local file to the backend input root. |
| backend_download | Download an input, output or temporary file to a local path. |
| workflow_new | Create and activate a blank workflow. |
| workflow_open | Open a saved workflow, or report its existing ID if already open. |
| workflow_download | Write the current Workflow JSON to a local file, including unsaved edits. |
| workflow_upload | Validate a local Workflow JSON and replace the selected editor graph. |
| workflow_save | Save a workflow, optionally under a new name or path. |
| run | Submit the selected graph once and return acceptance or validation errors. |
status, backend_status and backend_history accept an optional session_id; omission covers all connected sessions. Job results include all active jobs and jobs finished in the last 12 hours. Outputs provide path and type for download, not media contents or URLs. Errors omit full tracebacks.
Workflow validation and saving
Transfers use standard editor Workflow JSON: nodes, links, groups, positions, widget values, subgraphs and other graph metadata. This is not the API execution-prompt format.
workflow_upload parses JSON, checks its basic structure, refreshes the frontend node catalog, and validates a candidate in a detached frontend graph. Supported checks cover the native workflow schema, link consistency and missing node types, models and media references. Only successful validation activates and replaces the target graph. Failed checks return a compact issue list without replacing it.
Validation uses internal ComfyUI frontend APIs and can require compatibility updates. Unsupported APIs or failed catalog refreshes block replacement. These checks do not render or guarantee backend execution, parameter correctness or model compatibility. The backend still validates a run.
Upload changes the editor only. Saving and rendering are separate operations. workflow_save without a name uses its existing path; a temporary workflow returns NAME_REQUIRED. A new name/path cannot overwrite another saved workflow. Saving under a new name may create a new tab: use the returned ID. temporary means there is no saved backend file; modified means the graph differs from its loaded or saved state.
Operations on one page are queued, but there is no optimistic concurrency token. A later upload can overwrite edits made since download. After a timeout, inspect editor/backend status before retrying a save, upload or run: the previous operation may already have completed.
Files and node discovery
backend_upload({ session_id: "<session_id>", file: "/absolute/path/reference.png" })
backend_download({
session_id: "<session_id>", path: "renders/frame.png", type: "output",
file: "/absolute/path/frame.png"
})
backend_node_info({ session_id: "<session_id>", query: "image resize", limit: 10 })
backend_node_info({ session_id: "<session_id>", node_type: "LoadImage" })Upload supports the input root only, an optional filename, and native backend collision handling. There is no subfolder or overwrite parameter. Use the actual returned path in the workflow node; upload does not modify a graph. Download supports existing subfolders and input/output/temp types, streams to disk and refuses to overwrite an existing local file. Parent directories must exist.
backend_inputs_list preserves backend entries and ordering. root_only becomes false when an entry contains a folder separator. It does not scan workflow references or invent a recursive listing.
Node search returns compact paged summaries; an exact node_type returns its full native definition. Successful validated definitions are cached per session without a TTL. Successful uploads through the proxy and changed Authorization invalidate that cache. External backend changes require reconnecting. Frontend workflow validation refreshes its own catalog independently.
Authentication and proxy behavior
Each session has an in-memory cookie jar, including upstream HttpOnly and Secure cookies, and the latest browser Authorization header. Subsequent browser requests and MCP backend operations reuse it. Credentials are not returned in status or logs. Backend cookies are not exposed as localhost browser cookies, so separate proxy ports do not share sessions.
HTTPS and WSS are supported, but upstream certificate verification is intentionally disabled. The local proxy remains HTTP. Basic Auth challenges pass through to the browser; same-backend redirects are rewritten to the proxy. OAuth, captcha, JavaScript-managed cookies, absolute URLs and secure-context requirements may need additional compatibility work.
HTTP, WebSocket, uploads, downloads and Range responses are proxied. Selected UTF-8/ASCII HTML responses are decompressed and buffered for injection; binary content remains streamed. Content Security Policy is not relaxed, so a restrictive policy can prevent the bridge from loading. Nothing is installed on the backend.
Lifetime and updates
New CLI releases apply to subsequent calls. npm reuses downloaded package files when the version has not changed. Your MCP client refreshes the list of available tools when notified of a change. Updating the stdio adapter itself requires restarting it.
The running proxy retains its version and sessions until it stops. Compatible CLI updates continue using it. After it exits, the next call starts the updated proxy. New features that require a newer proxy become available after that restart.
The local proxy shuts down after 30 minutes of inactivity. Workflow operations, browser navigation and file transfers keep it active. After shutdown, connect again to establish a new session. ComfyUI and its running jobs continue independently.
Connecting again to the same normalized backend URL replaces its previous session after the new proxy and browser opening succeed. Its first proxy port is remembered for future connections. A busy port uses a free fallback without overwriting that preference.
CLI and development
npx -y --prefer-online mcp-comfyui-proxy@latest --version
npx -y --prefer-online mcp-comfyui-proxy@latest --help
npx -y --prefer-online mcp-comfyui-proxy@latest --tool-manifestThe executable is comfyui-mcp. --tool-manifest prints JSON without HTTP. --execute-tool NAME reads one JSON argument object from stdin and prints one MCP result as JSON.
git clone https://github.com/kucharskill/mcp-comfyui-proxy.git
cd mcp-comfyui-proxy
npm ci
npm run start:stdioLocal stdio uses --local to run this checkout's CLI without npm lookups. npm start runs HTTP manually. Files in extension/ are served directly: refresh the page after editing them. Restart HTTP after changing server code. Development checks are available through npm test.
On Windows, test-confy-server.cmd starts the latest stable ComfyUI in CPU mode using uvx and git. It updates an existing workspace or installs it on first use. The workspace and package cache are stored in %TEMP%\comfyui-test-latest. The test server listens at http://127.0.0.1:58189/ and stops automatically after one hour.
Diagnostics
status includes reverse_proxy_log_path. Session logs record important requests, writes, status codes, errors and WebSocket lifecycle events. Request bodies, credential values and URL query values are omitted. Logs do not capture arbitrary browser JavaScript errors or full backend tracebacks.
Runtime files use the operating-system temporary directory:
comfyui-mcp/<session_id>.jsonl: proxy diagnostics.comfyui-mcp/proxy-ports.json: preferred proxy ports.comfyui-mcp-runtime/http-<port>.log: HTTP process output.
Files may outlive a process. Sessions and credentials are not restored from them. extension/ contains injected page JavaScript, not a separately installed browser extension. TLS keys/certificates in test/fixtures/ are synthetic and excluded from npm.
License
MIT. See LICENSE.
