Skip to content
Back to search

mcp-comfy

Comfy MCP server

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

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

HTML

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

Choosing the ComfyUI address (important!)

- **LM Studio and ComfyUI on the same computer** → use `http://localhost:8188` (or `http://127.0.0.1:8188`). ComfyUI's default listen address works as-is. - **Two computers on a LAN** → use `http://<ComfyUI-PC-IP>:8188` and: 1. start ComfyUI with `--listen 0.0.0.0` (by default it only listens on `127.0.0.1` and is unreachable from other machines); 2. **assign fixed IP addresses to both computers in the router** (DHCP reservation). If the ComfyUI PC's IP changes, the servers will silently lose the target until you re-run the installer with the new URL.

macOS / Linux

Requirements: Python ≥ 3.10 (`brew install python`), LM Studio.

1. Clone/copy the whole repo (server `.py` files, workflow `.json` files, `installer/` folder). 2. Run:

   cd comfy-mcp/installer
   ./install.sh http://<ComfyUI-host>:8188

(without arguments it falls back to the default URL; if no suitable Python is found the script prints the exact `brew install python@3.14` commands). 3. Restart LM Studio (Developer → MCP → Restart). The `comfy-image-gen`, `comfy-image-edit` and `comfy-image-upscale` tools appear. 4. Paste the system prompt (below) into the model's System Prompt / Project Rules in LM Studio.

The script does: venv + `pip install "mcp<2" websocket-client Pillow`, substituting the ComfyUI URL into all servers, creating the working folders, registering the servers in `~/.lmstudio/mcp.json` (merge with a `.bak` backup; legacy `comfy_mcp_server`/`edit_mcp_server` entries are replaced with the new names).

Windows

Requirements: Python ≥ 3.10 (python.org installer with "Add python.exe to PATH", or `winget install Python.Python.3.14`), LM Studio.

1. Clone/copy the repo. 2. In PowerShell:

   cd comfy-mcp\installer
   .\install.ps1 http://<ComfyUI-host>:8188

3. Restart LM Studio (Developer → MCP → Restart). 4. Paste the system prompt (below).

The PowerShell installer performs the same steps as the bash one, with Windows paths: venv in `.venv\Scripts\python.exe`, inbox/results under `%USERPROFILE%`, config at `%USERPROFILE%\.lmstudio\mcp.json`.

Uninstall

# macOS / Linux
cd comfy-mcp/installer && ./uninstall.sh
# Windows
cd comfy-mcp\installer
.\uninstall.ps1

Removes the servers from `~/.lmstudio/mcp.json` (config backed up to `.bak`). Repo files and the venv are untouched.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 318 lines
  1. # comfy-mcp — MCP tools for image generation and editing via ComfyUI
  2. Three MCP servers for LM Studio that work with a (local or remote) ComfyUI
  3. instance. The ComfyUI address is an **installation variable**:
  4. `./installer/install.sh http://<ComfyUI-host>:8188` (macOS/Linux) or
  5. `.\installer\install.ps1 http://<ComfyUI-host>:8188` (Windows).
  6. | Server | Tools | Purpose |
  7. |---|---|---|
  8. | `comfy-image-gen` | `generate_image`, `check_image` | text-to-image generation (nvidia workflow) |
  9. | `comfy-image-edit` | `edit_image`, `check_image`, `list_images`, `convert_image` (+ `save_images` only with env `COMFY_ENABLE_SAVE_IMAGES=1`) | image editing by text instruction (qwen-image-edit) + format/quality conversion |
  10. | `comfy-image-upscale` | `upscale_image`, `check_image`, `list_images` | SeedVR2 neural upscaling |
  11. Key protocol feature: `edit_image` and `generate_image` **never wait for the
  12. result** — they queue the job in ComfyUI and immediately return a `job_id`
  13. ("task accepted"). Readiness is checked by repeated `check_image` calls, which
  14. return the finished image inline. This keeps the tool from hitting the MCP
  15. client's tool-call timeout (rendering takes 1–5 minutes).
  16. ## Monitoring: errors and progress
  17. - **Shared job registry.** All three servers mirror job statuses into
  18. `~/.comfy_mcp_jobs.json`. `check_image` on any server accepts any `job_id` —
  19. even if another server created the job or a server was restarted (finished
  20. jobs are re-read from disk). Entries older than 24 h are pruned automatically.
  21. - **Error/cancel detection.** The poller checks `status.status_str` in
  22. `/history/<prompt_id>` on every poll: if a job failed (e.g. a corrupt image in
  23. `LoadImage`) or was cancelled, `check_image` immediately returns the error
  24. description — node, its type and the exception text (e.g.
  25. `LoadImage (node 470): cannot identify image file ...`) — instead of waiting
  26. out the timeout.
  27. - **Progress percentage.** The servers listen to the ComfyUI WebSocket (`/ws`)
  28. and receive sampler `progress` events (requires the `websocket-client`
  29. package, installed by the installer). Progress shows up in `check_image`
  30. replies while rendering: `Progress: 10/25 steps (40%)`. Important: ComfyUI
  31. sends progress events **only to the submitting client** (by `client_id`), so
  32. progress is visible only for jobs submitted by the MCP servers themselves.
  33. ## How chat attachments reach the tools
  34. LM Studio stores chat attachments in `~/.lmstudio/user-files/` (on Windows:
  35. `%USERPROFILE%\.lmstudio\user-files\`). A background watcher thread inside
  36. `comfy-image-edit` copies new image attachments into the inbox folder
  37. automatically (keeping the original name with a `chat_` prefix); they then show
  38. up via `list_images`. On first run the historical library is only marked as
  39. seen — only new attachments are copied.
  40. Folders:
  41. - `~/comfy_edit_inbox` (Windows: `%USERPROFILE%\comfy_edit_inbox`) — incoming
  42. images for editing/upscaling (automatic + manual), shared by the edit and
  43. upscale servers;
  44. - `~/comfy_images` (Windows: `%USERPROFILE%\comfy_images`) — saved results of
  45. generation, editing and upscaling.
  46. ## Format/quality conversion
  47. `convert_image(paths, format, quality)` in `comfy-image-edit` converts images
  48. to JPG (quality 1–100, default 90) or PNG, saving the result next to the
  49. original (inbox files stay in the inbox). Typical use case: rendering is
  50. noticeably faster with a JPG source, so shrink large PNGs before `edit_image`:
  51. 1. `list_images()` → paths;
  52. 2. `convert_image(paths=[...], format="jpg", quality=90)` → converted paths;
  53. 3. `edit_image(..., source_image=<jpg path>)`.
  54. JPEG does not support transparency — alpha is flattened onto a white background.
  55. ## Upscaling (comfy-image-upscale)
  56. `upscale_image(source_image, multiplier | longer_size, scale_method)` — SeedVR2
  57. 7B neural upscaling via ComfyUI. Scale is set either by `multiplier` (0.01–8,
  58. default 2) or by `longer_size` (target longer side in pixels, aspect ratio
  59. preserved) — the second is more precise for "make it 2048px". `scale_method`
  60. (default `lanczos`) is the interpolation used for the pre-resize inside the
  61. pipeline. The result is a PNG in `~/comfy_images` (compressing the upscale
  62. result with a lossy conversion inside the workflow is pointless; apply
  63. `convert_image` afterwards if needed). Same two-phase protocol: `job_id` →
  64. repeated `check_image`; upscaling is heavy — rendering can take noticeably
  65. longer than editing.
  66. ## Workflow files
  67. The three `*.json` files in the repo root are **required** — each server loads
  68. its workflow at submit time and sends it to ComfyUI with every job. They are
  69. plain ComfyUI workflow API exports and contain **no local data** (no paths,
  70. addresses or machine info; only node ids, parameters and model filenames listed
  71. in the table below). Nothing needs to be downloaded into ComfyUI to use them —
  72. they are submitted over the API, not installed. If you use different models,
  73. export your own workflow in API format and replace the corresponding file
  74. (keep the node ids referenced in the server's header constants — see the
  75. requirements table below).
  76. ## Requirements on the ComfyUI side
  77. The `*.json` files in this repo are **ComfyUI workflow API exports** — they are
  78. submitted to ComfyUI as-is. The target ComfyUI instance must therefore have the
  79. same models and custom nodes installed, otherwise jobs fail with execution
  80. errors (the error text is returned by `check_image`, so a missing model is easy
  81. to identify).
  82. | Workflow file | Models (in ComfyUI `models/` folders) | Custom nodes |
  83. |---|---|---|
  84. | `nvidia-image-gen.json` | `z_image_turbo_bf16.safetensors` (diffusion models), `qwen_3_4b.safetensors` (text encoders), `ae.safetensors` (vae) | core nodes only |
  85. | `image_qwen_image_2_1_image_edit.json` | `qwen_image_2.1_int8_convrot.safetensors`, `qwen3vl_8b_int8_convrot.safetensors`, `qwen_image_2.1_vae_bf16.safetensors`, `qwen3.5_9b_qwen_image_2.1_pe_i2i.int8_convrot.safetensors` | `SaveImageAdvanced`, `TextEncodeQwenImage21`, `QwenImage21Cache`, `ComfySwitchNode`, `BatchImagesNode`, `PrimitiveStringMultiline`, `TextGenerate`, `PreviewAny` |
  86. | `utility_seedvr2_7b_int8_upscale_image.json` | `seedvr2_7b_int8_convrot.safetensors`, `seedvr2_ema_vae_fp16.safetensors` | SeedVR2 custom nodes (`SeedVR2Preprocess`, `SeedVR2Conditioning`, `SeedVR2PostProcessing`), `ResizeImageMaskNode`, `JoinImageWithAlpha`, `VAEEncodeTiled`, `VAEDecodeTiled` |
  87. If you use different models/workflows, export your own workflow in API format
  88. (ComfyUI: "Workflow → Export (API)") and replace the corresponding `.json`
  89. file — the servers reference nodes by id, so keep the node ids used in the
  90. server's `*_SERVER`-style constants (save-node id and text/size inputs) or
  91. update them at the top of the server file.
  92. ## Installation
  93. ### Choosing the ComfyUI address (important!)
  94. - **LM Studio and ComfyUI on the same computer** → use
  95. `http://localhost:8188` (or `http://127.0.0.1:8188`). ComfyUI's default
  96. listen address works as-is.
  97. - **Two computers on a LAN** → use `http://<ComfyUI-PC-IP>:8188` and:
  98. 1. start ComfyUI with `--listen 0.0.0.0` (by default it only listens on
  99. `127.0.0.1` and is unreachable from other machines);
  100. 2. **assign fixed IP addresses to both computers in the router** (DHCP
  101. reservation). If the ComfyUI PC's IP changes, the servers will silently
  102. lose the target until you re-run the installer with the new URL.
  103. ### macOS / Linux
  104. Requirements: Python ≥ 3.10 (`brew install python`), LM Studio.
  105. 1. Clone/copy the whole repo (server `.py` files, workflow `.json` files,
  106. `installer/` folder).
  107. 2. Run:
  108. ```bash
  109. cd comfy-mcp/installer
  110. ./install.sh http://<ComfyUI-host>:8188
  111. ```
  112. (without arguments it falls back to the default URL; if no suitable Python
  113. is found the script prints the exact `brew install python@3.14` commands).
  114. 3. Restart LM Studio (Developer → MCP → Restart). The `comfy-image-gen`,
  115. `comfy-image-edit` and `comfy-image-upscale` tools appear.
  116. 4. Paste the system prompt (below) into the model's System Prompt / Project
  117. Rules in LM Studio.
  118. The script does: venv + `pip install "mcp<2" websocket-client Pillow`,
  119. substituting the ComfyUI URL into all servers, creating the working folders,
  120. registering the servers in `~/.lmstudio/mcp.json` (merge with a `.bak` backup;
  121. legacy `comfy_mcp_server`/`edit_mcp_server` entries are replaced with the new
  122. names).
  123. ### Windows
  124. Requirements: Python ≥ 3.10 (python.org installer with "Add python.exe to
  125. PATH", or `winget install Python.Python.3.14`), LM Studio.
  126. 1. Clone/copy the repo.
  127. 2. In PowerShell:
  128. ```powershell
  129. cd comfy-mcp\installer
  130. .\install.ps1 http://<ComfyUI-host>:8188
  131. ```
  132. 3. Restart LM Studio (Developer → MCP → Restart).
  133. 4. Paste the system prompt (below).
  134. The PowerShell installer performs the same steps as the bash one, with Windows
  135. paths: venv in `.venv\Scripts\python.exe`, inbox/results under
  136. `%USERPROFILE%`, config at `%USERPROFILE%\.lmstudio\mcp.json`.
  137. ### Uninstall
  138. ```bash
  139. # macOS / Linux
  140. cd comfy-mcp/installer && ./uninstall.sh
  141. ```
  142. ```powershell
  143. # Windows
  144. cd comfy-mcp\installer
  145. .\uninstall.ps1
  146. ```
  147. Removes the servers from `~/.lmstudio/mcp.json` (config backed up to `.bak`).
  148. Repo files and the venv are untouched.
  149. ## Using with other MCP clients
  150. The servers are standard **stdio MCP servers** — nothing in them is specific to
  151. LM Studio. Any MCP client can run them: point the client at
  152. `<repo>/.venv/bin/python` (macOS/Linux) or `<repo>\.venv\Scripts\python.exe`
  153. (Windows) with the server script as the argument. The installer only automates
  154. venv creation and the registration below.
  155. | Client | Registration | Notes |
  156. |---|---|---|
  157. | LM Studio | `~/.lmstudio/mcp.json` (done by the installer) | chat-attachment auto-copy watcher is enabled |
  158. | ZCode | workspace/user MCP config, same server entries | chat attachments have real file paths → enable `COMFY_ENABLE_SAVE_IMAGES=1` in the server env to get `save_images` |
  159. | OpenCode | `opencode.json` → `"mcp": {"comfy-image-edit": {"type": "local", "command": [...], "env": {...}}}` | same entries as below |
  160. | Claude Desktop / Cursor | `claude_desktop_config.json` / `~/.cursor/mcp.json` → standard `mcpServers` block | attachments have no paths → use the inbox flow (`list_images`) |
  161. | Ollama | not an MCP client by itself | needs a bridge (e.g. `mcpo`) that exposes MCP tools over the Ollama chat API |
  162. The generic registration block (works for most clients):
  163. ```json
  164. {
  165. "mcpServers": {
  166. "comfy-image-gen": {
  167. "command": "/path/to/comfy-mcp/.venv/bin/python",
  168. "args": ["/path/to/comfy-mcp/comfy_mcp_server.py"],
  169. "env": {}
  170. },
  171. "comfy-image-edit": {
  172. "command": "/path/to/comfy-mcp/.venv/bin/python",
  173. "args": ["/path/to/comfy-mcp/edit_mcp_server.py"],
  174. "env": { "COMFY_ENABLE_SAVE_IMAGES": "1" }
  175. },
  176. "comfy-image-upscale": {
  177. "command": "/path/to/comfy-mcp/.venv/bin/python",
  178. "args": ["/path/to/comfy-mcp/upscale_mcp_server.py"],
  179. "env": {}
  180. }
  181. }
  182. }
  183. ```
  184. Client-agnostic notes:
  185. - the two-phase `job_id`/`check_image` protocol exists precisely because tool-call
  186. timeouts differ per client — it works everywhere;
  187. - the system prompt (below) needs the `list_images`-based attachment flow for
  188. clients without file-path attachments; for clients like ZCode enable
  189. `save_images` and prefer it;
  190. - `jobstore` and the inbox folder are shared across all clients on the machine.
  191. ## System prompt for LM Studio
  192. Paste into the model settings (System Prompt) or Project Rules:
  193. ```
  194. You have image tools from the comfy-image-gen, comfy-image-edit and comfy-image-upscale MCP servers:
  195. - generate_image(prompt, width, height, steps) — a new image from scratch.
  196. - list_images() — images in the inbox folder (~/comfy_edit_inbox), newest first.
  197. - convert_image(paths, format, quality) — convert to jpg (quality 1-100, default 90) or png;
  198. the result is saved next to the original. Use before edit_image when the source is
  199. a large PNG: a JPG source renders noticeably faster.
  200. - edit_image(prompt, source_image, [reference_image], steps) — edit by path.
  201. Returns a job_id immediately ("task accepted").
  202. - upscale_image(source_image, multiplier | longer_size, scale_method) — SeedVR2 neural
  203. upscale (a multiplier, e.g. 2 or 4, or a target longer side in pixels). Also returns
  204. a job_id immediately.
  205. - check_image(job_id) — readiness poll. Present on all three servers and accepts
  206. ANY job_id (jobs live in a shared registry): poll via the same server you started
  207. the job with, but any server works if needed. It returns one of: the finished
  208. image (inline), "still rendering" with progress (Progress: 10/25 steps, 40%),
  209. or an error description (which node failed and why).
  210. Rules:
  211. - "Draw/generate" → generate_image.
  212. - ANY image the user mentions in the chat (attached, dropped, pasted, or generated/edited
  213. earlier) → IMMEDIATELY call list_images: chat attachments and job results automatically
  214. land in the inbox (the former a few seconds after sending). NEVER try to save an
  215. attachment yourself and never ask the user to save anything — just take the path from
  216. list_images. If the image is not in the list yet, wait a couple of seconds and call
  217. list_images again.
  218. - The user gave a file path directly → use it as-is, without list_images.
  219. - If the image still never appears in the inbox → ask the user to put it into
  220. ~/comfy_edit_inbox and call list_images again.
  221. - Before edit_image, shrink a large PNG source (> ~3 MB): convert_image(paths, "jpg", 90) →
  222. use the converted path. Final images are usually requested as JPG too — convert the
  223. result with the same tool.
  224. - "Enhance/upscale/make bigger" → upscale_image; use longer_size when the user names a
  225. target size (e.g. "to 2048px"), otherwise a multiplier of 2-4. The upscale result is a
  226. PNG in ~/comfy_images; compress it with convert_image if needed.
  227. - Two images for edit_image: source_image — what to edit (decide by content),
  228. reference_image — what to put on/add.
  229. - If edit_image/upscale_image returned a job_id → keep calling check_image until the
  230. image arrives, NEVER restart the job. Rendering takes 1–5 minutes (upscaling longer);
  231. do not ask the user between polls — just poll check_image and report the progress
  232. included in the response.
  233. - If check_image returned an error (e.g. "cannot identify image file" — a corrupt
  234. image) → tell the user the error text and suggest replacing the source. Do not restart
  235. the same job with the same files and do NOT switch to generate_image.
  236. - If check_image replied "Unknown job_id" → the job was lost (the server restarted
  237. between calls). Report it and create the job again — exactly once.
  238. ```
  239. ## Project structure
  240. ```
  241. comfy-mcp/
  242. ├── comfy_mcp_server.py # generation MCP server (comfy-image-gen)
  243. ├── edit_mcp_server.py # editing MCP server + convert_image (comfy-image-edit)
  244. ├── upscale_mcp_server.py # SeedVR2 upscale MCP server (comfy-image-upscale)
  245. ├── jobstore.py # shared cross-server job registry
  246. ├── nvidia-image-gen.json # generation workflow API
  247. ├── image_qwen_image_2_1_image_edit.json # editing workflow API
  248. ├── utility_seedvr2_7b_int8_upscale_image.json # upscale workflow API
  249. └── installer/
  250. ├── install.sh # macOS/Linux installer (venv + LM Studio registration)
  251. ├── install.ps1 # Windows installer
  252. ├── uninstall.sh # removes entries from mcp.json (bash)
  253. └── uninstall.ps1 # removes entries from mcp.json (PowerShell)
  254. ```
  255. ## Fine-tuning (edit_mcp_server.py)
  256. | Constant | Default | Meaning |
  257. |---|---|---|
  258. | `PC` | `http://localhost:8188` | ComfyUI address (rewritten by the installer) |
  259. | `INBOX_DIR` | `~/comfy_edit_inbox` | incoming images |
  260. | `LM_FILES_DIR` | `~/.lmstudio/user-files` | where the watcher picks up chat attachments |
  261. | `WATCH_INTERVAL` | `5` s | attachment scan period |
  262. | `CHECK_WAIT_DEFAULT` | `20` s | how long one `check_image` call waits |
  263. | `CHECK_WAIT_MAX` | `120` s | upper bound of `wait` for `check_image` |
  264. (the same applies to `comfy_mcp_server.py`, except the inbox/watch constants)
  265. The watcher thread lives inside the MCP server, i.e. attachment copying works
  266. while LM Studio is connected to the server (always, in an active session). The
  267. "already copied" state is stored in `.lmstudio_seen.json` next to the server.
  268. Русская версия: [README_RU.md](README_RU.md)

Ratings and comments

Sign in to rate this skill.

Sign in

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