ComfyUI FL-MCP

Built-in MCP chat, tool server, and browser bridge for controlling ComfyUI.

Demo

What It Does

ComfyUI FL-MCP adds an MCP-native workflow chat to ComfyUI and exposes the same tools to external clients such as Claude Desktop, Cursor, Codex, and other agentic development environments. The built-in assistant is powered by Ren and appears directly in the ComfyUI sidebar.

It provides three control paths:

flowchart LR
    A[Built-in MCP chat] --> B[backend/mcp_server.py]
    G[External MCP client] --> B
    B --> C[ComfyUI HTTP API127.0.0.1:8188]
    B --> D[FL-MCP bridge backend127.0.0.1:8000]
    D --> E[Open ComfyUI browser tab]
    E --> F[Live graph canvas]

Highlights

• 133 MCP tools for workflow inspection, graph editing, queue control, Manager v4, model discovery, filesystem inspection, custom node development, and diagnostics.
• Built-in MCP chat, powered by Ren, with streaming responses, persistent conversation history, chronological tool activity, and approval cards.
• Bring your own model through LM Studio, Ollama, OpenAI, OpenRouter, Anthropic, Claude Code, Codex, or a custom OpenAI-compatible endpoint.
• Use existing subscriptions from Claude Code or Codex without copying OAuth credentials into FL-MCP.
• Canvas-aware editing keeps generated nodes from overlapping and makes ComfyUI’s Fit View respect the open chat panel.
• Embedded ComfyUI bridge diagnostics remain available from the assistant sidebar.
• Standalone MCP mode for REST-only control when no browser tab is open.
• Live canvas bridge for frontend-only actions such as reading the current graph, selecting/focusing nodes, screenshots, and layout edits.
• Safety gates keep destructive/write actions disabled by default.
• Custom-node aware coding tools scoped to ComfyUI/custom_nodes.

Installation

Manual Install

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/filliptm/ComfyUI_FL-MCP.git
cd ComfyUI_FL-MCP
pip install -r requirements.txt

Restart ComfyUI. The sidebar should show a Ren tab with a chat-bubble icon. Inside that tab, the main panel is labeled MCP.

ComfyUI Desktop

Desktop installations can contain more than one Python environment. Install FL-MCP requirements with the interpreter used by the running ComfyUI app, not an unqualified pip. From the ComfyUI directory on macOS or Linux:

./.venv/bin/python -m pip install -r custom_nodes/ComfyUI_FL-MCP/requirements.txt

On Windows:

.\.venv\Scripts\python.exe -m pip install -r .\custom_nodes\ComfyUI_FL-MCP\requirements.txt

Restart ComfyUI after installation. If the backend cannot start, Ren → Settings → Bridge diagnostics displays the launcher failure and log path.

Bridge settings

The local defaults work for a standard ComfyUI install. To change the backend launch mode, bind address, ports, ComfyUI path, extra model paths file, logging, generation waiting behavior, or server-side safety gates, open Ren → Settings → Bridge & safety.

Bridge settings are validated and stored locally in .fl_mcp/bridge_settings.json. Changes take effect after restarting ComfyUI. If an older install has a .env file, supported values are imported once when the JSON settings file does not yet exist. The legacy file is left untouched and is no longer read after that import.

Quick Start

1. Start ComfyUI.
2. Open ComfyUI in your browser.
3. Open the Ren sidebar tab.
4. Select the provider badge in the top bar, or open More options → Settings.
5. Select a provider, discover or choose a model, then choose Save and test.
6. Ask about the open workflow. Tool calls remain in chronological order alongside the response that produced them.

Model providers

API credentials are stored in the operating-system keychain when available. Claude and Codex subscription modes remain separate from direct Anthropic and OpenAI API access and billing.

To use a Claude Pro, Max, Team, or Enterprise subscription, install Claude Code and sign in once:

claude auth login

Then choose Claude subscription under Settings → Connection. FL-MCP checks the official Claude Code login, does not read or copy its OAuth credentials, and keeps direct Anthropic API-key access as a separate provider.

To use a ChatGPT Plus, Pro, Business, Edu, or Enterprise subscription with Codex, install the Codex CLI and sign in once:

codex login

Then choose Codex subscription under Settings → Connection. FL-MCP uses the official Codex SDK and its existing ChatGPT login without reading or copying OAuth credentials. Direct OpenAI API-key access remains a separate provider and billing path.

Routine canvas edits can run without an extra prompt. Queueing, workflow deletion, package changes, file writes, Git operations, and process restarts display an approval card before the tool runs by default. Choose Always allow on a card to remember that MCP tool, or enable Bypass all approval prompts under Settings → Permissions to skip every chat approval. The server-side safety gates described below still apply in either mode.

Using the built-in chat

• The fixed top bar shows MCP, connection status, and the active provider and model.
• Each open workflow tab has its own selected conversation and unsent draft. Switching tabs restores that workflow’s chat and stops any response that was still running in the previous tab.
• Select History to search, rename, archive, restore, or permanently delete conversations.
• History remains global: use Switch workflow for a conversation whose workflow is open, or attach an older unassigned conversation to the active workflow.
• Tool calls stay at their chronological position in the conversation. Consecutive identical calls collapse into a single row with an ×N count while retaining each call’s details.
• Approval cards support Deny, Allow once, and persistent per-tool Always allow decisions. Saved rules can be cleared from Settings → Permissions.
• Bypass all approval prompts disables the chat approval layer globally. It does not override the server-side workflow, file, Git, Manager, or process safety gates.
• Wait for generation completion by default keeps a single queue_workflow tool call open while ComfyUI runs, avoiding repeated model-driven status requests. Each call can override the saved behavior and timeout.
• The composer remains fixed below the scrollable conversation. Jump to present scrolls smoothly when new activity arrives out of view.
• ComfyUI’s native Fit View accounts for the visible canvas beside the open chat panel.
• Automatic node insertion uses real node bounds and graph extents to avoid stacking new nodes on top of existing nodes.

Deterministic workflow building

Ren uses the same two-step graph compiler for a new workflow, a small edit, or a multi-branch refinement:

1. compile_workflow_refinement_spec resolves the request against the active native, partner, and custom-node catalog, the current canvas (which may be empty), exact node schemas, dynamic inputs, attachments, stable defaults, and active exact-schema verified connection lessons.
2. apply_workflow_graph_patch refreshes and recompiles that canonical plan, then applies it as one guarded transaction without queueing the workflow.

The root GraphPatch v2 plan describes edges directly, so it can create fan-in, fan-out, merges, multiple terminal outputs, retained-node updates, removals, and widget-to-input connections such as wiring a video’s FPS into Video Combine. Before changing the canvas it checks workflow, graph, catalog, schema, slot, value, attachment, and cycle preconditions. Afterward it verifies the exact final graph while preserving unrelated workflow state. Any mismatch restores the complete original snapshot. Ambiguous node selection is returned to the user as a choice instead of being resolved alphabetically.

Scoped GraphPatch v3 applies the same transaction, verification, rollback, and idempotency guarantees inside one exact subgraph definition while retaining the full root workflow as the mutation authority. Public subgraph input/output boundaries are schema-attested ports; compiler-only virtual nodes never appear on the apply wire.

The compiler resolves semantic endpoint intent to exact dynamic paths and prefers direct connections. If source and target types are incompatible, it may search a bounded capability hypergraph for a unique supported local converter. This is schema-driven for every loaded class rather than hardcoded to named nodes. Equal routes require a user choice; partner/API/heavy/output nodes are never inferred without explicit intent, and exact/no-extra requests disable inference entirely.

Branch navigation and scoped editing

Ren can discover workflow splits, reconvergences, terminal arms, and maximal non-branching segments without enumerating every source-to-sink path. Each region receives an exact branch_id for mutation authority and an ID-independent structural fingerprint for comparison. IDs are typed, scope-aware, and pinned to the active workflow and graph before any navigation or edit.

Natural requests such as “jump to the upscale branch,” “compare the preview and final branches,” or “replace this whole branch” use the branch tools first. Ambiguous matches return bounded candidates and perform no selection. Exact navigation selects and fits every branch node as one locked UI action. Root and authorized nested clone, replace, and remove requests compile back into the same atomic GraphPatch writer, including the complete incident-edge boundary, so sibling nodes, connections, values, rectangles, groups, reroutes, definitions, and workflow fields remain unchanged.

After a successful branch mutation, resolve_workflow_branch_successor re-attests the persisted GraphPatch result, rediscovers every affected scope, and returns exact predecessor-to-successor lineage. It returns a singular successor only when exactly one exists; clones or replacement DAGs may correctly return several, while a verified removal returns an empty successor list. No lineage result is guessed from a label or stale fingerprint.

Clone is deliberately bounded to private branch regions whose widgets and boundaries can be reconstructed exactly. External sources are shared. For a non-terminal or reconvergent branch, the copied region’s external outputs stay detached and the result reports their exact edge IDs; the merge target and every sibling remain untouched. Upload/attachment or credential-bearing inputs, unreproducible execution state, and unacknowledged risky partner/output work fail closed rather than being copied implicitly.

Nested branches use recursive {container_node_id, subgraph_id} scope paths. Unique definitions can be edited in place. Reused definitions require an explicit shared-definition acknowledgement listing every affected instance; instance-only copy-on-write detachment is rejected until that separate operation is supported. Virtual subgraph inputs and outputs are schema-attested boundary ports rather than ordinary editable nodes. Branch tools never run or queue the workflow.

Node creation and connections remain visibly sequential on the canvas. Small graphs retain the deliberate step-by-step feel, while larger patches use a bounded animation budget so visual pacing does not make complex builds slow.

External MCP clients

To use FL-MCP from another client:

1. Open More options → Bridge diagnostics and confirm the backend and browser bridge are connected.
2. Configure the MCP client to run backend/mcp_server.py.
3. Call mcp_capability_audit to see which capabilities are available.

Operating Modes

The bridge backend does not run inside ComfyUI’s main event loop. It runs as a separate Python process and prefers 127.0.0.1:8000. If that port belongs to another service, the embedded launcher selects an available fallback port and reports the actual URL through Bridge diagnostics and /fl_mcp/launcher/status.

Assistant Data and Security

• Non-secret assistant settings, approval mode, and per-tool Always allow rules are stored under .fl_mcp/chat_settings.json.
• Non-secret bridge, path, logging, and safety settings are stored under .fl_mcp/bridge_settings.json.
• Conversations, messages, run state, approvals, and tool activity are stored locally in .fl_mcp/chat.db.
• Existing conversations from .ren/ren.db are imported once when that database is present. Legacy provider secrets and session metadata are not copied.
• API credentials use the OS keychain when available, then environment variables, with an in-memory fallback if the keychain cannot be used.
• Claude subscription mode delegates authentication and credential storage to the installed Claude Code CLI. FL-MCP stores only the Claude session ID needed to resume each MCP chat conversation.
• Codex subscription mode delegates authentication and credential storage to Codex. FL-MCP stores only the Codex thread ID needed to resume each MCP chat conversation.
• Assistant output is rendered with a small local Markdown renderer. It does not load a CDN renderer or insert model text as raw HTML.
• The assistant starts a separate MCP stdio process for each active run. Multiple embedded or external MCP clients can share one browser session without receiving each other’s tool results.

Safety Gates

Read-only tools and workflow-editing tools are available by default so Ren can prepare and execute ordinary ComfyUI workflows. Workflow writes can still be disabled explicitly. Writing custom-node files, mutating Manager state, pushing git commits, and controlling processes must be explicitly enabled.

Open Ren → Settings → Bridge & safety → Server-side capabilities to change these gates, save, and restart ComfyUI.

Tool Inventory

FL-MCP currently exposes 133 tools.

New clients should use compile_workflow_refinement_spec followed by the returned unchanged apply_workflow_graph_patch request for both new builds and edits. The older plan/apply workflow and linear-refinement tools remain compatibility APIs.

API Endpoints

The bridge backend prefers 127.0.0.1:8000; use Bridge diagnostics or /fl_mcp/launcher/status to find its current URL when a fallback port is active.

The built-in chat uses local routes under /api/chat:

These routes are local UI plumbing for the embedded chat. MCP clients should continue to use backend/mcp_server.py rather than treating the chat routes as a remote public API.

ComfyUI also receives custom-node launcher routes:

Common Workflows

Troubleshooting

Optional Agent Skill

This repo includes an optional Codex-style skill at:

skills/workflow-assistant/

The skill gives MCP clients workflow-first guidance for inspecting, editing, debugging, compacting, validating, and queueing ComfyUI graphs through FL-MCP. It is optional and does not change the FL-MCP server runtime.

Install it by copying or symlinking the skill folder into your client skills directory. For Codex:

mkdir -p ~/.codex/skills
ln -s /path/to/ComfyUI/custom_nodes/ComfyUI_FL-MCP/skills/workflow-assistant \
  ~/.codex/skills/workflow-assistant

Then start a new client session and invoke it explicitly when useful:

Use $workflow-assistant to inspect and clean up my open ComfyUI workflow.

You still need to configure the comfyui-fl-mcp MCP server separately as described in Quick Start.

Development

cd /path/to/ComfyUI/custom_nodes/ComfyUI_FL-MCP
python -m pip install -r requirements.txt
python -m pytest

Useful local checks:

python -m compileall -q backend mcp_daemon.py __init__.py
python -I -c "import runpy; runpy.run_path('backend/mcp_server.py', run_name='embedded_mcp'); runpy.run_path('backend/server.py', run_name='embedded_server')"
node --test tests/js/*.test.mjs
for f in web/js/*.js; do node --check "$f"; done
python -m pip check

Support

If this saves you time building ComfyUI workflows or custom nodes, support ongoing FL custom node development: