{"id":"ed280b47-c40a-43af-abc4-51197e9d4eb9","slug":"comfyui-local-mcp","kind":"mcp","name":"ComfyUI-Local-MCP","summary":"","owner":"XXJones21","repoUrl":"https://github.com/XXJones21/ComfyUI-Local-MCP","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-05-23T22:15:37.000Z","addedAt":"2026-10-21T17:27:07.513Z","logoUrl":"https://avatars.githubusercontent.com/u/34466796?u=c1d15fb9813e5af1d54295da45d37381a102d73a&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T22:47:10.339Z","sample":false,"url":"https://conduits.dev/tools/comfyui-local-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"comfy-local-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# ComfyLocalMCP\n\n**A local-first, device-aware ComfyUI client + MCP server for *building* with local image/video generation.** Use it as a plain Python library inside your own pipelines, or as an MCP server + Claude Code plugin so an agent can build, optimize, and run ComfyUI workflows that actually fit your GPU.\n\n> 🙏 **Shout-out to the ComfyUI + MCP community.** ComfyUI is the de-facto engine for local GenAI, and there's great prior art for driving it from agents — if you want a feature-rich, interactive \"talk to ComfyUI from Claude\" experience, check out [**artokun/comfyui-mcp**](https://github.com/artokun/comfyui-mcp). ComfyLocalMCP is a complementary, narrower take: **Python-native + embeddable-as-a-library + VRAM/hardware-aware**, aimed at people wiring ComfyUI into their own products.\n\n## Why this one?\n\n- **Library *and* MCP.** Import `comfy_local_mcp` directly in your Python pipeline (deterministic, no agent in the loop), *or* run the MCP server for agent-driven use. Same code, both shapes.\n- **Device-aware.** `device_report` + `recommend_workflow` read your actual free VRAM (via ComfyUI's `/system_stats`) and pick a workflow + settings that fit — and only ever suggest workflows whose models/nodes are actually installed. No more 10-minute thrash because Flux + a resident LLM didn't fit on a 16 GB card.\n- **Workflows as parameterized templates.** Named ComfyUI graphs with logical override points (`prompt`, `seed`, `width`, `height`, `steps`).\n- **Two transports.** `direct` (vanilla ComfyUI on `:8188`) or `rust` (any supervised ComfyUI fronting `/comfy/*` with restart/health/watchdog).\n\n## Features\n\nFour surfaces over one local ComfyUI: a Python **library**, an **MCP server**, a **Claude Code plugin**, and a **workflow template** system.\n\n### Python library (`comfy_local_mcp`)\nEmbed it directly in your own pipelines — no agent required.\n\n- `ComfyClient` — async core: `submit`, `stream` (normalized progress events), `wait_for_result`, `fetch_result`, `download`, plus `object_info` and `system_stats` for discovery/diagnostics.\n- `ComfyImageGenerator` / `ComfyVideoGenerator` — sync, drop-in generators returning a stable diffusers-like dict (`filepath`, `filename`, `image_data`, `metadata{asset_url, prompt_id, seed, …}`).\n- `load_workflow` / `list_workflows` — load and patch a named template.\n- `comfy_local_mcp.progress.stream` — convenience progress iterator.\n\n### MCP server — 9 tools\n\n| Tool | Purpose |\n|---|---|\n| `device_report()` | GPU name + total/free VRAM + ComfyUI/torch/python versions (via `/system_stats`; falls back to `nvidia-smi`). |\n| `recommend_workflow(goal, vram_free_gb?, resident_model_gb?)` | **The differentiator.** Picks a workflow + overrides that *fit* the GPU, accounts for a resident model (e.g. an LLM), downsizes when tight, and only suggests workflows whose models/nodes are installed. Returns `{workflow, overrides, fits, budget_gb, rationale, warnings, candidates}`. |\n| `list_workflows()` | Available workflow names. |\n| `list_models(node_class)` | What a loader node accepts (catches \"model not installed\" before you submit). |\n| `generate_image(prompt, workflow, width, height, seed?, steps?)` | High-level text→image. |\n| `generate_video(prompt, image_input, workflow)` | High-level image→video. |\n| `submit_workflow(name, overrides)` / `get_result(prompt_id)` | Low-level build/execute loop for tuned graphs. |\n| `health()` | Transport + ComfyUI reachability. |\n\nTools return asset URLs/paths, not raw image bytes (keeps agent context small).\n\n### Claude Code plugin\n- **`comfy-local` subagent** — a **build → optimize → execute** loop: `device_report` → `recommend_workflow` → confirm models → run → report, with honest \"this won't fit, here's the lighter option\" behavior instead of silent VRAM thrash.\n- **`comfy-local-setup` skill** — cross-platform install walkthrough (detect GPU, install/locate ComfyUI, register the comfy-local + Hugging Face MCPs, bootstrap a fitting model, smoke-test) + references for per-OS install and model-download recipes.\n- **Slash commands** — `/comfy-gen` (generate, GPU-optimized) and `/comfy-setup`.\n- **`.mcp.json`** auto-wires the server over stdio, so installing the plugin makes the tools appear.\n\n### Workflow templates\nComfyUI API-format graphs wrapped as `{_meta, _overrides, graph}`, patched by logical name (`prompt`, `seed`, `width`, `height`, `steps`):\n\n| Workflow | Model / use |\n|---|---|\n| `scene_image_flux` | Flux.1-dev Q4 GGUF, portrait 9:16 — the proven hero path |\n| `scene_image_sdxl_turbo` | SDXL-Turbo, 1-step draft/fast |\n| `scene_image_sdxl_lora` | SDXL + LoRA, styled |\n| `scene_video_ltx2` | **LTX-2.3 GGUF two-stage text→video, portrait 9:16 — the proven video hero path** (verified on a 16 GB RTX 4080, ~45 s compute per second of output) |\n| `scene_video_ltx` | LTX-Video 0.9.x, image→video (legacy/fast) |\n| `scene_video_wan22` | Wan2.2, cinematic video |\n| `skybox_sdxl_turbo` | 360° skybox |\n\n### Compatibility shim\n`shim/` ships an `engram_comfy` package that re-exports the API, so code importing the pre-rename name keeps working.\n\n### Not included (v1, by design)\nModel downloading (compose with the [Hugging Face MCP](https://huggingface.co/mcp) + `hf` CLI), free-form graph authoring, an asset/history database, and cloud GPU.\n\n## Install\n\n```bash\npip install -e \".[mcp]\"          # library + MCP server (FastMCP)\n```\n\nRequires a running ComfyUI (`http://127.0.0.1:8188`). New to ComfyUI? Run the bundled **setup** skill (Claude Code) or see `skills/setup/references/`.\n\n## Library quickstart\n\n```python\nfrom comfy_local_mcp import ComfyImageGenerator\n\ngen = ComfyImageGenerator(default_workflow=\"scene_image_flux\")\nresult = gen.generate_image(\n    prompt=\"first person POV, misty forest at dusk, glowing mushrooms\",\n    width=768, height=1344,\n)\nprint(result[\"filepath\"], result[\"metadata\"][\"asset_url\"])\n```\n\n## MCP server\n\n```bash\ncomfy-local-mcp --transport http      # shared server on http://127.0.0.1:9400/mcp\n# or stdio (for a Claude Code plugin): comfy-local-mcp --transport stdio\n```\n\nTools: `device_report`, `recommend_workflow`, `list_workflows`, `list_models`, `generate_image`, `generate_video`, `submit_workflow`, `get_result`, `health`.\n\nRegister with Claude Code:\n```bash\nclaude mcp add --transport http comfy-local http://127.0.0.1:9400/mcp\n```\n\n## Claude Code plugin\n\nThis repo is also a Claude Code plugin: it ships the **`comfy-local`** subagent (build → optimize → execute) and the **setup** skill, and auto-wires the MCP server via `.mcp.json` (stdio). Pair it with the [Hugging Face MCP](https://huggingface.co/mcp) for model discovery (downloads use the `hf` CLI — see the setup skill).\n\n## Configuration\n\nNothing about your machine is hardcoded. A per-user config at **`~/.comfy-local-mcp/config.json`** (override with `COMFY_LOCAL_MCP_CONFIG`) holds your transport/URL, output dir, and a **models map** — logical roles (`flux_unet`, `t5`, `clip_l`, `flux_vae`, `sdxl_turbo_ckpt`, `ltx_ckpt`, the LTX-2.3 video roles `ltx2_unet`/`ltx2_gemma`/`ltx2_connectors`/`ltx2_video_vae`/`ltx2_audio_vae`/`ltx2_distilled_lora`/`ltx2_upscaler`, …) → the actual filenames you have installed. Workflows bind to those instead of the built-in defaults; explicit per-call overrides still win.\n\nYou don't hand-write it: on first run the **setup skill / `comfy-local` subagent** calls `suggest_config` (inspects your installed ComfyUI models) and `save_config` to populate it. Missing roles are reported so you know what to download. With no config at all, the package still runs against a default ComfyUI on `:8188` using the workflows' fallback filenames.\n\nResolution order everywhere: **explicit arg → env var → config file → built-in default.**\n\n| Var | Default | Purpose |\n|---|---|---|\n| `COMFY_TRANSPORT` | `direct` | `direct` (ComfyUI `:8188`) or `rust` (supervised `/comfy/*` on `:8765`) |\n| `COMFY_BASE_URL` | per transport | ComfyUI/supervisor base URL |\n| `COMFY_TIMEOUT_S` | `300` | Per-job timeout |\n| `COMFY_ASSETS_DIR` | `~/.comfy-local-mcp/assets` | Where downloaded outputs land |\n| `COMFY_LOCAL_MCP_CONFIG` | `~/.comfy-local-mcp/config.json` | Config file location |\n| `COMFY_MCP_TRANSPORT` | `http` | MCP transport (`http` or `stdio`) |\n| `COMFY_MCP_PORT` | `9400` | HTTP MCP port |\n\n## Status\n\nVerified on **Windows + NVIDIA (RTX 4080)**. macOS/Linux and non-NVIDIA paths are best-effort — issues and PRs welcome. v1 deliberately does **not** rebuild model downloading (use the HF MCP + `hf` CLI) or free-form graph editing.\n\n## License\n\nMIT © Joshua Jones\n"}