@fre4x/comfyui

ComfyUI MCP Server

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

Tools

• comfyui_inspect_node: List available nodes or inspect one node schema.
• comfyui_discover_workflows: Scan known workflow directories for stored JSON files.
• comfyui_get_workflow: Normalize a stored workflow and list its editable inputs.
• comfyui_save_workflow: Save a workflow into local ./workflows with optional edits.
• comfyui_workflow_run: Run a stored workflow with optional overrides.
• comfyui_wait_for_workflow: Wait for workflow completion with a timeout.

comfyui_discover_workflows filters out non-workflow JSON files and distinguishes between API workflows and Web UI graphs whose conversion was validated against the live node schema.

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).
• 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"
      }
    }
  }
}

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 timeout value in seconds to comfyui_workflow_run. For lower-level control, use comfyui_wait_for_workflow with prompt_id and timeout.

comfyui_workflow_run accepts either a stored workflow reference (workflow_id / workflow_file_path) or an inline workflow JSON object.

Stored Workflow Reuse

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

• Save a workflow with comfyui_save_workflow into local ./workflows
• Inspect editable paths with comfyui_get_workflow
• Persist edits with comfyui_save_workflow overrides
• Reuse it with comfyui_workflow_run

comfyui_workflow_run and comfyui_save_workflow both accept dot-notation overrides in canonical node.inputs.field form, plus shorter aliases like node.seed, node.text, node.positive_prompt, and, for Web UI workflows, node.widgets[index].

{
  "workflow_id": "pony-portrait-v1",
  "overrides": {
    "2.seed": 67890,
    "6.positive_prompt": "cinematic dragon portrait"
  },
  "await": true,
  "timeout": 90
}

If your client serializes nested arguments first, overrides may also be sent as a JSON string:

{
  "workflow_id": "pony-portrait-v1",
  "overrides": "{\"2.seed\":67890,\"6.positive_prompt\":\"cinematic dragon portrait\"}"
}

To inspect editable inputs and semantic hints for agent editing:

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

comfyui_get_workflow and comfyui_save_workflow both return:

• high_signal_inputs: the most useful prompt/model/sampler controls first
• input_groups: grouped counts for prompts, models, sampling, output, etc.
• combo-backed inputs include options_count, options_preview, and options_truncated
• override_examples: copy-ready payloads using the preferred override aliases

These appear in both content.text and structuredContent so agents can steer complex workflows without having to scan every literal widget first.

When comfyui_wait_for_workflow times out, the error now includes a queue snapshot in both content.text and structuredContent to show whether the prompt is still pending or has disappeared from the server queue.

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_file_path": "pony-portrait-v1.json",
  "overrides": {
    "6.text": "studio lighting, ultra detailed",
    "7.filename_prefix": "pony-portrait-agent"
  },
  "output_file_name": "pony-portrait-agent.json",
  "overwrite": true
}