ComfyUI MCP Server

An MCP server to interact with ComfyUI remotely. Probe server state, inspect node definitions, reuse existing workflows, and execute them.

Concept (server-API-first)

Local and remote ComfyUI are equal. Everything about Comfy goes over HTTP (COMFYUI_SERVER_URL) — including saved workflows and templates. The MCP process must never assume it shares a filesystem with Comfy (no ~/ComfyUI install-path heuristics, no “local vs remote” branching).

| Layer | Role | |-------|------| | Primary catalog | Comfy HTTP: userdata workflows/ (/userdata) + core /templates + custom /workflow_templates | | Extension | MCP-host agent workspace: cwd (root *.json), ./workflows/ (depth ≤ 2), ~/.fre4x-comfyui/workflows, optional directory_path — clones and agent-owned JSON only |

Reuse-first: discover an existing server/template (or MCP clone) workflow, apply scalar overrides, run. Clone with save_workflow before graph surgery. Do not invent Comfy workflow JSON.

Lifecycle: discover → (optional) clone → edit (overrides / surgical tools) → upload input images → run.

workflow_ref examples: server:workflows/image_sdxl_simple.json, template:default/image_z_image_turbo, or an MCP-host path/filename/discover id.

Tools

• comfyui_inspect_node: Search or inspect node schemas (query is tokenized; use node_class for full schema).
• comfyui_discover_workflows: Search server userdata + templates (+ MCP clones); prefer these over creating graphs.
• comfyui_get_workflow: Normalize an existing workflow and list its editable inputs.
• comfyui_save_workflow: Clone an existing workflow into an MCP-host JSON file (working copy; not for authoring new graphs).
• comfyui_workflow_run: Run an existing workflow_ref with scalar overrides.
• comfyui_wait_for_workflow: Wait for workflow completion with a timeout.
• comfyui_interrupt_workflow: Interrupt the running job and optionally clear the pending queue.
• comfyui_upload_image: Upload a workspace image into ComfyUI input for LoadImage.
• comfyui_list_models: List installed checkpoints, LoRAs, VAEs, UNets, and related files.
• comfyui_connect_nodes: Connect nodes semantically with type validation and auto-wiring.
• comfyui_insert_node: Insert node with optional pipeline interception between source and target.
• comfyui_remove_node: Remove a node and automatically clean dependent connections.
• comfyui_list_connections: List workflow connections, port types, and detected semantic roles.

comfyui_discover_workflows searches server userdata + templates first, then MCP-host extension paths. It filters non-workflow JSON, labels origin, and distinguishes API vs Web UI graphs when hydrated. Prefer runnable:true (or get_workflow on a template) — do not invent new graphs. Use query with OR-style tokens (FaceID, ControlNet, OpenPose, SDXL, …) to find existing workflows.

comfyui_get_workflow warns when combo values (checkpoints, VAEs, images) are not present on the live server, and keeps LoadImage / ControlNet / VAE in the high-signal override list so custom pose/character workflows are runnable without verbose: true.

Pass an existing workflow_ref (server:…, template:…, or MCP path). To create a working copy, call comfyui_save_workflow. Inline full-graph authoring is not supported.

Do not assume structuredContent is what the model actually sees. Many MCP clients surface content.text to the model first and treat structuredContent as secondary machine-readable metadata. Every actionable detail that an agent needs for its next step must therefore appear in content.text as well: node options, filenames, URLs, prompt IDs, and recovery hints.

Setup

Environment Variables

• COMFYUI_SERVER_URL: The URL of your ComfyUI server (default: http://localhost:8188).
• COMFY_API_KEY: Optional API key for Comfy Cloud or an authenticated proxy.
• COMFY_API_HEADER: Header name for that key (default: X-API-Key; use Authorization for Bearer proxies).
• COMFYUI_DEFAULT_WORKFLOW: Optional path, filename, or discover id used when workflow_ref is omitted.
• COMFYUI_UPLOAD_ROOT: Extra directory allowed by comfyui_upload_image (workspace cwd is always allowed).
• COMFYUI_OUTPUT_DIR: Directory where workflow generated images are copied/saved. Output structure is {COMFYUI_OUTPUT_DIR}/comfyui/{prompt_id}/{filename}. Precedence: COMFYUI_OUTPUT_DIR > MCP_WORKSPACE_DIR > process.cwd().
• MCP_WORKSPACE_DIR: Workspace directory injected by MCP clients (or set manually) for image saving. Output structure is {MCP_WORKSPACE_DIR}/comfyui/{prompt_id}/{filename}.
• COMFYUI_DISABLE_WORKSPACE_SAVE: Set to true to completely disable copying generated images to disk (returns in-memory base64 only).
• MOCK: Set to true to use mock data instead of a real server.

Claude Desktop Configuration

{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["-y", "@fre4x/comfyui"],
      "env": {
        "COMFYUI_SERVER_URL": "http://your-server-ip:8188",
        "COMFYUI_OUTPUT_DIR": "/path/to/my/images"
      }
    }
  }
}

Mock Mode

For development or testing without a running ComfyUI instance:

MOCK=true npx @fre4x/comfyui

Workflow API Format

comfyui_workflow_run and comfyui_save_workflow both normalize workflows into ComfyUI API Format before execution or persistence. In ComfyUI, enable "Developer Mode" in settings, then click "Save (API Format)" if you want the raw graph JSON. Standard Web UI workflow JSON is also accepted and normalized automatically.

If you want a single call that submits and waits, pass await: true with a short timeout (default 25 seconds) to comfyui_workflow_run. Host MCP clients often cut longer blocking waits — if you get a timeout, call comfyui_wait_for_workflow again with the same prompt_id. For lower-level control, set await: false then poll wait. Use comfyui_interrupt_workflow to stop a running job; clear_queue defaults to false.

comfyui_workflow_run accepts a stored workflow reference (workflow_ref, or the deprecated workflow_id / workflow_file_path aliases). Do not paste full workflow JSON into tool arguments. If COMFYUI_DEFAULT_WORKFLOW is set, the stored reference may be omitted.

Stored Workflow Reuse

The stored-workflow tools let you avoid re-sending large API JSON blobs and give agents a stable local edit loop.

1. Discover or point at an existing workflow with workflow_ref
2. Inspect editable paths with comfyui_get_workflow
3. Persist edits with comfyui_save_workflow + small overrides
4. Reuse it with comfyui_workflow_run

Prefer unique global override keys when the graph has only one of that role:

{
  "workflow_ref": "pony-portrait-v1",
  "overrides": {
    "positive_prompt": "cinematic dragon portrait",
    "seed": 67890
  },
  "await": true,
  "timeout": 90
}

Node-scoped aliases still work: 2.seed, 6.positive_prompt, node.inputs.field, and Web UI node.widgets[index]. If a global key is ambiguous, the error lists the valid node-scoped paths.

overrides must be a small JSON object (never a stringified blob, never a full graph).

To inspect editable inputs and semantic hints for agent editing:

{
  "workflow_ref": "pony-portrait-v1",
  "include_prompt": false
}

Pass verbose: true when you need every editable input rather than the high-signal subset.

comfyui_get_workflow and comfyui_save_workflow both return:

• editable_inputs: high-signal controls by default (full list with verbose: true)
• values are truncated to value_preview unless verbose: true
• input_groups: grouped counts for prompts, models, sampling, output, etc.
• combo-backed inputs include options_count, options_preview, and options_truncated
• preferred_override_paths / truncated override_examples for copy-ready keys

comfyui_discover_workflows returns override_keys only (no prompt values).

comfyui_wait_for_workflow returns at most max_images native images (default 2, preferring output over temp). All outputs remain listed in image_refs with source_type/subfolder for comfyui_upload_image. Structured content omits the raw history prompt graph.

comfyui_workflow_run also performs a preflight pass against the live /object_info schema before submission so invalid combo-backed values such as missing checkpoints, LoRAs, VAEs, or input filenames fail fast without entering the ComfyUI queue.

To save a new or edited workflow locally:

{
  "workflow_ref": "pony-portrait-v1.json",
  "overrides": {
    "positive_prompt": "studio lighting, ultra detailed",
    "filename_prefix": "pony-portrait-agent"
  },
  "output_file_name": "pony-portrait-agent.json",
  "overwrite": true
}

Image upload

Image bytes never pass through the model. Provide exactly one reference:

1. Previous run: prompt_id + filename from image_refs / wait text. The server copies ComfyUI output into input.
2. Workspace file: file_path.

{
  "prompt_id": "77777777-7777-7777-7777-777777777777",
  "filename": "ComfyUI_00001_.png"
}

{
  "file_path": "/path/in/workspace/source.png",
  "filename": "source.png"
}

The tool returns the LoadImage filename to use in overrides. file_path uploads stay inside the workspace (and optional COMFYUI_UPLOAD_ROOT). prompt_id sources are read from the previous run's workspace copy or ComfyUI /view.