comfy-draftsman

The MCP server that drafts ComfyUI workflows a human can actually read.

A local-first Model Context Protocol server that lets coding agents (Claude Code, Claude Desktop, Cursor, ...) build, repair, port, validate, and run ComfyUI workflows against your own ComfyUI instance — and deliver them as clean, organized, fully-labeled workflows: computed layout, colored stage groups, titled nodes, green-highlighted "knobs you may touch", and markdown guidance notes explaining which tuned settings to leave alone and why.

Every agent tool for ComfyUI can emit raw API-format JSON — a working but unreadable pile of unpositioned nodes. Draftsman's reason to exist is the finished drawing:

The note above was generated automatically: draftsman detected the checkpoint was a DMD-distilled SDXL merge and tuned CFG to 1.0, 4 steps, lcm/sgm_uniform — then wrote down why, so the person opening the workflow doesn't "fix" it back to CFG 7.

What it does

• Draft — seed from ComfyUI's bundled templates (always current with the latest models) or build from scratch with semantic graph operations (add_node, connect, set_widget — validated against the live instance's schemas; set_widget by index reaches a pack's JS-only widgets).
• Organize — the differentiator: pipeline-stage auto-layout, colored groups, human titles (✅ Positive Prompt, Base Pass), green highlights on user-editable knobs, and generated notes in two registers: "👇 type your prompt here" vs "⚙️ turbo model — CFG stays at 1.0". Everything you'd tweak (source images, canvas size, models/LoRAs, prompts) reads left-to-right first, and preview/Show Text nodes sit right beside the node they display — no tracing wires across the canvas to figure out which sampler made which image.
• Diagnose & modernize — hand it an old broken workflow: it reports every incompatibility against your live instance (renamed nodes, changed widget layouts, missing model files with closest-installed suggestions) and resolves missing custom nodes to installable packs via the official Comfy Registry.
• Port — retarget across model families (sdxl → flux, ...): swaps loader topology (checkpoint ⇄ separate UNET/CLIP/VAE loaders) and rewires consumers, retunes CFG/steps/samplers and technique nodes (FaceDetailer settings are family-specific — there is no universal detailer config), swaps latent node classes, picks installed model files, and flags everything needing human judgment.
• Validate & prove — structural + live validation, then an actual render with an inline preview, before the workflow is ever delivered.
• V3 dynamic combos — modern nodes whose choices reveal conditional sub-widgets (COMFY_DYNAMICCOMBO_V3 — e.g. SaveImageAdvanced's format, Depth-Anything-3's mode/output) are first-class: their values are set, round-tripped, validated, and serialized to the API's dotted-key form (output.normalization), so a graph containing them runs end-to-end through the draftsman alone. The rest of the V3 io system is handled alongside them: autogrow inputs (COMFY_AUTOGROW_V3 — a growing socket list like BatchImagesNode's images) expand to their real, connectable slot names with the dotted API keys the backend actually matches on, match types wire freely the way ComfyUI's own executor treats them, and inputs ComfyUI flags as widget-rendered (socketless/widgetType) are set as widgets rather than mistaken for required sockets.
• Run & watch — run any workflow (one you just built, or one already saved in your ComfyUI) and see the output right in the conversation: previews come back as downscaled thumbnails to keep the chat light, with view_output fetching full resolution on demand. Long renders can queue in the background (wait=False) with live step progress via get_run_status. If the instance already has a long queue, draftsman says so instead of silently waiting — and can queue your test run to go next (front=True) without touching the jobs already in line. Upload source images for img2img/inpaint, and manage the queue when something needs interrupting. (wait=False + get_run_status polling for long/paid renders — see run_workflow's docstring)
• Learn — a two-layer knowledge system: a curated per-family floor (SD1.5/SDXL/SD3.5/FLUX/Krea-2/Chroma/Qwen-Image/Wan/LTX, variant-aware for turbo/lightning/DMD/distills) plus a persistent learned overlay: when the agent researches better settings for a new model, record_learning saves them so every future session starts smarter. A learned entry can carry its own detect block, so a brand-new model researched once becomes self-detecting next session instead of being mistaken for a lookalike family.
• Stay current — ground truth is your running ComfyUI (/object_info, live templates, live model lists), never a bundled snapshot.

Requirements

• Python ≥ 3.11 with uv (or pip)
• A running ComfyUI instance (default http://127.0.0.1:8188)

Install

Claude Code:

claude mcp add comfy-draftsman \
  -e COMFYUI_URL=http://127.0.0.1:8188 \
  -e COMFYUI_MOUNT_DIR=/path/your/agent/can/reach \
  -- uvx --from git+https://github.com/EnragedAntelope/comfy-draftsman comfy-draftsman

Claude Desktop / other MCP clients (mcpServers config):

{
  "mcpServers": {
    "comfy-draftsman": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/EnragedAntelope/comfy-draftsman", "comfy-draftsman"],
      "env": {
        "COMFYUI_URL": "http://127.0.0.1:8188",
        "COMFYUI_MOUNT_DIR": "/path/your/agent/can/reach"
      }
    }
  }
}

Prefer the published package? uv tool install comfy-draftsman (or pip install comfy-draftsman) puts the server on PATH, and both configs above shorten to plain uvx comfy-draftsman / "args": ["comfy-draftsman"]. The git+https form above tracks unreleased commits.

COMFYUI_MOUNT_DIR is optional but recommended: it's a folder your agent (or a sandboxed client like Claude Desktop / Cowork) can actually read, and save_output / run_workflow relocate finished renders there — otherwise renders stay inside ComfyUI's output/ tree and every save needs an explicit dest_dir. On Windows use a native path, e.g. C:\\Users\\you\\comfy-renders. See Configuration for all environment variables.

Then just ask your agent things like:

"Build me a Krea workflow with LoRA support and a face detailer, labeled so my friend can use it."

"Here's an old SD1.5 workflow JSON that doesn't load anymore — fix it and port it to SDXL."

"Take this workflow I downloaded and make it neat and organized."

It checks your hardware before you spend forty minutes on a download: ask for guidance on a model family your GPU can't comfortably hold and the answer comes back with a fit verdict — what's needed, what you have, and what to do about it. When it fits, it says nothing.

Updating

uvx caches, and it will not tell you. uv keys a git+https:// dependency on the resolved commit hash, and uvx reuses a cached environment rather than re-resolving — so a config pointing at the git URL keeps running whatever commit it first installed, indefinitely, with no warning. A plain uvx comfy-draftsman behaves the same way once published.

Pick whichever shape you prefer:

| Config | Updates | Trade-off | |---|---|---| | uvx comfy-draftsman@latest | Every time the server starts | Needs PyPI reachable at start-up — uv errors rather than falling back to its cache on a network failure | | uv tool install comfy-draftsman | When you run uv tool upgrade comfy-draftsman | Starts offline, but you have to remember | | uvx --from git+https://… | Only after uv cache clean comfy-draftsman | Tracks unreleased commits; silently stale otherwise |

@latest is the right default for most people. If you work offline often, take the uv tool install row and run uv tool upgrade comfy-draftsman (or uv tool upgrade --all) when you want a new version.

To find out what you're running, ask your agent to call check_setup — the first line of its report is the running comfy-draftsman version. The draftsman://capabilities resource carries it too.

To hear about new versions, watch the repo on GitHub: Watch → Custom → Releases. Every tagged release publishes to PyPI and creates a GitHub Release whose notes are that version's CHANGELOG.md section. The server itself never phones home — it talks only to your ComfyUI and (read-only) the Comfy Registry, and checking for updates is deliberately your call, not a background poll.

Migrating an existing install costs nothing but a config edit. Session state and learned knowledge live in ~/.comfy-draftsman/ and saved workflows live in ComfyUI's own browser, so neither depends on how the server was installed — change the args line, restart your client, and optionally uv cache clean comfy-draftsman to reclaim the old checkout.

Configuration

| Env var | Default | Purpose | |---|---|---| | COMFYUI_URL | http://127.0.0.1:8188 | The ComfyUI instance to drive | | DRAFTSMAN_SESSION_DIR | ~/.comfy-draftsman/sessions | Where in-progress workflows persist | | DRAFTSMAN_LEARNED_DIR | ~/.comfy-draftsman/learned | Persistent learned model knowledge | | COMFYUI_MOUNT_DIR | (unset) | Folder a sandboxed client can reach; save_output (and run_workflow's auto-relocate) copy finished renders — images, video, audio — here out of ComfyUI's output/ tree | | DRAFTSMAN_TIMEOUT | 30 | HTTP timeout (seconds) | | DRAFTSMAN_ELICITATION | on | off never opens a confirmation dialog and always takes the ask-in-chat fallback — for a client whose dialog never renders | | COMFY_API_KEY | (unset) | Comfy Org API key for partner/* nodes (Luma, Seedance, Kling, Runway); injected into the prompt payload's extra_data so headless queues authenticate |

Using with Claude Cowork / Code

ComfyUI's save nodes only ever write inside ComfyUI's own output/ tree, so a finished render has to be copied out before a sandboxed agent can open, edit, or show it to you. That copy lands in COMFYUI_MOUNT_DIR — and the one rule that makes it work is:

COMFYUI_MOUNT_DIR must be a folder that both the draftsman server (next to ComfyUI) and your agent's sandbox can see — typically your Cowork/Code workspace directory, or a subfolder of it.

• Set it to an absolute path. The server runs with its own working directory (MCP hosts often launch it from a system directory like System32), so a relative dest_dir/save_dir would resolve somewhere invisible — draftsman now refuses a relative path with a clear error rather than misplacing your render.
• Same machine (typical): point it at your project folder, e.g. COMFYUI_MOUNT_DIR=I:\source\repos\my-project\renders (Windows) or /home/you/project/renders. run_workflow auto-relocates the finished output files there — images, video and audio alike — and returns their saved_paths; the agent opens those paths directly. (Relocation needs finished files, so it applies to a blocking run; a background wait=False run relocates afterwards with save_output(prompt_id=...), and says so rather than ignoring save_dir.)
• Check readiness first. get_instance_info (call it first anyway) returns a relocation block — {"configured": true, "writable": true, "path": ...} when you're good to go, or a hint telling you to set COMFYUI_MOUNT_DIR when you're not. check_setup is the dedicated doctor — it also confirms ComfyUI itself is reachable and never raises — and the draftsman://capabilities resource reports the