@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.

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.

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 this form:

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

To inspect editable inputs and semantic hints for agent editing:

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

To save a new or edited workflow locally:

{
  "workflow_file_path": "pony-portrait-v1.json",
  "overrides": {
    "6.inputs.text": "studio lighting, ultra detailed",
    "7.inputs.filename_prefix": "pony-portrait-agent"
  },
  "output_file_name": "pony-portrait-agent.json",
  "overwrite": true
}