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:

Path	Works When	Best For
MCP chat (built in)	ComfyUI is open with the bridge backend running	Chatting with, inspecting, and editing the current graph without leaving ComfyUI
ComfyUI REST tools	ComfyUI is running on `127.0.0.1:8188`	Models, queue, history, Manager v4, files, diagnostics
Browser bridge tools	ComfyUI is open in a browser tab with FL-MCP connected	Current canvas JSON, node selection, layout, screenshots, frontend commands

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

Highlights

108 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

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

Model providers

Provider	Authentication	Model selection
LM Studio	Local endpoint; no API key	Discovers loaded or available models
Ollama	Local endpoint; no API key	Discovers installed models
OpenAI API	OpenAI API key	Editable API model field
OpenRouter API	OpenRouter API key	Editable API model field
Anthropic API	Anthropic API key	Editable API model field
Claude subscription	Existing Claude Code login	Dropdown of supported Claude Code models and aliases
Codex subscription	Existing Codex login	Dropdown populated from the installed Codex CLI
Custom endpoint	Optional API key	Editable OpenAI-compatible model field

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 → Model & provider. 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 → Model & provider. 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 → Tool approvals 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.
Select History to search, rename, archive, restore, or permanently delete conversations.
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 → Tool approvals.
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.

External MCP clients

To use FL-MCP from another client:

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

Claude Desktop / Cursor-style MCP config

Use the Python executable from the same environment where dependencies are installed.

{
  "mcpServers": {
    "comfyui-fl-mcp": {
      "command": "python",
      "args": [
        "/path/to/ComfyUI/custom_nodes/ComfyUI_FL-MCP/backend/mcp_server.py"
      ]
    }
  }
}

This enables REST-friendly tools. Browser-only tools return requires_browser_bridge unless you also connect a live bridge session.

Enable live browser/canvas tools

Browser-only tools need a connected ComfyUI tab. Open ComfyUI, open the Ren sidebar panel, then use Bridge diagnostics to confirm the live connection before running the MCP server:

FL_MCP_MODE=subprocess \
FL_MCP_SESSION_ID=<session-id-from-sidebar> \
FL_MCP_WS_URL=ws://127.0.0.1:8000/ws \
python backend/mcp_server.py

Use this mode for tools like:

workflow_get_current_json
workflow_load_json
find_node
set_node_values
connect_nodes
modify_layout
take_screenshot

Operating Modes

Mode	Process Model	How It Starts	Lifetime
Embedded subprocess	Separate child process	ComfyUI imports this custom node and starts `backend/server.py`	Tied to ComfyUI parent process
Daemon launcher	Separate daemon process	Sidebar start route launches `mcp_daemon.py`	Can be stopped via launcher route
MCP stdio server	MCP client subprocess	MCP client starts `backend/mcp_server.py`	Tied to the MCP client

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.

Gate	Enables
Workflow writes (on by default)	Canvas mutation, workflow load/save/delete, settings writes, history deletes
Custom node writes	Writing files, applying patches, creating custom node packs
Git writes	Git commit and push tools under custom nodes
Manager mutations	ComfyUI Manager install/update/uninstall queue actions
Process control	Starting, stopping, and restarting managed ComfyUI processes

Tool Inventory

FL-MCP currently exposes 108 tools.

Capability and Utility Tools

Tool	What it does
`mcp_capability_audit`	Audits bridge, REST, Manager, assets, and safety-gate state
`calculate_expressions`	Evaluates batches of math expressions for layout or parameter planning
`wait`	Waits for a short period, useful after queueing work
`generate_seed`	Generates a random seed
`generate_float`	Generates a random float
`generate_int`	Generates a random integer
`random_choice`	Picks a random item from a list
`get_system_info`	Reports OS, Python, paths, and environment details

Live Workflow and Canvas Tools

These generally require the browser bridge.

Tool	What it does
`query_workflow`	Queries the graph with filters, traversal, and aggregation
`workflow_overview`	Summarizes the current workflow
`workflow_diagram`	Generates a Mermaid workflow diagram
`workflow_get_current_json`	Reads the active workflow as editable JSON or API prompt JSON
`workflow_load_json`	Loads workflow JSON into the active canvas
`workflow_get_tabs`	Lists open workflow tabs and active tab
`workflow_close_current`	Closes the active workflow tab
`workflow_duplicate_current`	Duplicates the active workflow tab
`find_node`	Finds a node by ID, type, or title
`create_nodes`	Creates one or more nodes
`remove_nodes`	Removes nodes
`bypass_nodes`	Bypasses nodes
`unbypass_nodes`	Unbypasses nodes
`pin_nodes`	Pins nodes
`unpin_nodes`	Unpins nodes
`select_nodes`	Selects nodes in the UI
`get_current_node_selection`	Reads the current selected nodes
`focus_on_nodes`	Fits the canvas view to nodes, selection, or graph
`take_screenshot`	Captures the current canvas
`get_node_values`	Reads widget values from a node
`set_node_values`	Sets widget values on a node
`get_node_slots`	Reads detailed input/output slot metadata
`connect_nodes`	Connects two nodes
`connect_nodes_batch`	Connects multiple node pairs
`auto_connect_workflow`	Auto-connects nodes based on type compatibility
`get_layout`	Reads node positions and sizes
`modify_layout`	Applies manual layout or auto-layout

Workflow Files and Tabs

Tool	What it does
`workflow_list_files`	Lists saved workflow files from ComfyUI user data
`workflow_read_file`	Reads saved workflow JSON
`workflow_save_current`	Saves the current workflow
`workflow_rename_file`	Renames or moves a workflow file
`workflow_delete_file`	Deletes a workflow file

Frontend Command Tools

Tool	What it does
`frontend_list_commands`	Lists registered ComfyUI frontend commands
`frontend_execute_command`	Executes a frontend command by ID
`frontend_list_keybindings`	Lists frontend commands and keybindings

Queue, Jobs, History, and Execution Tools

Tool	What it does
`queue_workflow`	Queues the current workflow and optionally waits for a terminal result
`cancel_workflow`	Cancels current execution
`enable_auto_queue`	Enables auto-queue
`disable_auto_queue`	Disables auto-queue
`set_batch_count`	Sets workflow batch count
`get_queue_status`	Reads frontend queue status
`get_queue_status_details`	Reads detailed ComfyUI queue and active execution state
`delete_queue_items`	Deletes items from the ComfyUI execution queue
`comfy_jobs_list`	Lists native ComfyUI jobs
`comfy_job_get`	Reads a job by prompt/job ID
`get_execution_history`	Reads queue and history from ComfyUI
`get_execution_details`	Reads detailed execution state for one run
`clear_error_buffer`	Clears the bridge error buffer
`comfy_history_delete`	Deletes history entries or clears history

ComfyUI REST, Models, Assets, and Files

Tool	What it does
`comfy_status`	Checks ComfyUI process and HTTP reachability
`comfy_get_logs`	Reads recent managed ComfyUI logs
`comfy_free_memory`	Unloads models and/or frees memory
`comfy_settings_get`	Reads ComfyUI settings
`comfy_settings_set`	Writes ComfyUI settings
`comfy_upload_image`	Uploads an image from inside the ComfyUI tree
`comfy_upload_mask`	Uploads a mask from inside the ComfyUI tree
`comfy_models_list`	Lists model folders or files
`comfy_workflow_templates_list`	Lists or reads workflow templates
`comfy_global_subgraphs_list`	Lists or reads global subgraphs
`comfy_node_replacements_get`	Reads node replacement mappings
`comfy_assets_list`	Lists assets when the assets feature is enabled
`comfy_asset_get`	Reads one asset metadata record
`comfy_asset_upload`	Uploads a ComfyUI-root file to assets
`comfy_assets_upload`	Alias for asset upload
`comfy_tags_list`	Lists asset tags
`comfy_list_folders`	Lists ComfyUI folders with filtering and sorting
`comfy_read_file`	Reads files inside approved ComfyUI folders
`comfy_search_resources`	Searches ComfyUI files
`extract_workflow_from_image`	Extracts workflow metadata from PNG/WebP images
`comfy_restart`	Restarts a managed ComfyUI process

Node Library and Compatibility Tools

Tool	What it does
`node_library_search`	Searches available ComfyUI node types
`node_library_get_details`	Reads detailed metadata for a node type
`node_library_find_compatible`	Finds compatible node types for connections

ComfyUI Manager Tools

Tool	What it does
`manager_v4_status`	Reports Manager v4 availability and queue status
`manager_v4_queue_status`	Reads Manager v4 queue status
`manager_v4_queue_action`	Queues a confirmation-gated Manager v4 action
`manager_v4_installed_packs`	Lists installed custom node packs
`manager_v4_snapshots`	Lists Manager snapshots
`manager_v4_node_mappings`	Finds node-to-pack mappings
`manager_v4_external_models`	Searches external model definitions
`manager_queue_action`	Queues install/update/uninstall/disable actions
`manager_queue_status`	Reads Manager queue status
`manager_queue_start`	Starts the Manager worker queue
`manager_queue_reset`	Resets the Manager queue
`manager_search_nodes`	Searches Manager custom node packs
`manager_get_node_mappings`	Finds which pack provides a node type
`manager_check_updates`	Checks installed packs for updates
`manager_search_external_models`	Searches Manager external models

Custom Node Development Tools

All paths are scoped under ComfyUI/custom_nodes.

Tool	What it does
`custom_nodes_list_packs`	Lists installed custom node packs
`custom_nodes_read_file`	Reads a bounded line range from a custom node file
`custom_nodes_read_file_excerpt`	Reads a bounded excerpt from a large file
`custom_nodes_search`	Searches custom node code with ripgrep
`custom_nodes_write_file`	Writes a full file
`custom_nodes_apply_patch`	Applies a unified diff
`custom_nodes_create_pack`	Creates a starter custom node pack
`custom_nodes_validate_pack`	Runs Python compile validation
`custom_nodes_git_status`	Shows git status for a custom node repo
`custom_nodes_git_diff`	Shows git diff
`custom_nodes_git_commit`	Commits changes
`custom_nodes_git_push`	Pushes changes

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.

Endpoint	Purpose
`GET /health`	Health and active sessions
`GET /api/config`	Browser client config
`GET /api/mcp/status`	MCP bridge status
`POST /api/mcp/shutdown`	Stop daemon mode backend
`GET /api/sessions`	Connected browser/MCP WebSocket sessions
`WS /ws`	Browser/MCP bridge WebSocket
`GET /api/comfy/status`	Managed ComfyUI process status
`GET /api/comfy/logs`	Managed ComfyUI logs

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

Endpoint group	Purpose
`GET /api/chat/status`	Provider, model, credentials, bridge, and active-run status
`/api/chat/settings`	Read or update non-secret provider settings
`/api/chat/models`	Discover models for the selected provider
`/api/chat/credentials/{provider}`	Store or remove API credentials
`/api/chat/claude/` and `/api/chat/codex/`	Check or start subscription CLI authentication
`/api/chat/conversations*`	Create, load, rename, archive, restore, or delete conversations
`/api/chat/runs*`	Start, stream, or cancel assistant runs
`/api/chat/approvals/{approval_id}`	Deny, allow once, or always allow a high-impact tool

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:

Route	Purpose
`GET /fl_mcp/launcher/status`	Backend launcher status
`POST /fl_mcp/launcher/start`	Start daemon backend
`POST /fl_mcp/launcher/stop`	Stop daemon backend

Common Workflows

Ask what workflow is open

Open ComfyUI in a browser.
Open the Ren sidebar and confirm Bridge diagnostics reports a live browser connection.
Ask the built-in chat about the workflow, or ask an external MCP client to call workflow_get_current_json or workflow_overview.

Clean up or compact a graph layout

Useful tools:

get_layout
modify_layout
focus_on_nodes
workflow_get_current_json
workflow_load_json

Inspect custom nodes before editing

Useful tools:

custom_nodes_list_packs
custom_nodes_search
custom_nodes_read_file_excerpt
custom_nodes_git_diff
custom_nodes_validate_pack

Enable Custom node writes under Ren → Settings → Bridge & safety only when you want the MCP client to write files or apply patches.

Troubleshooting

Browser-only tools say requires_browser_bridge

Open ComfyUI in a browser, open the Ren sidebar, and check More options → Bridge diagnostics. REST tools can run without the browser bridge, but live graph tools need the frontend connection.

Claude or Codex subscription is unavailable

Confirm the matching CLI is installed and authenticated:

claude auth status
codex login status

Return to Settings → Model & provider, select the subscription provider, and use its refresh action. FL-MCP never substitutes an API key provider for a subscription provider.

The chat UI did not update after installing a new version

Restart ComfyUI when Python dependencies or backend code changed. Then hard-refresh the browser so ComfyUI reloads the frontend extension.

Backend did not start

Check:

curl http://127.0.0.1:8188/fl_mcp/launcher/status
curl http://127.0.0.1:8000/health

The launcher response includes backendUrl. Use that URL for the health check if port 8000 was occupied.

Logs are written under:

ComfyUI/custom_nodes/ComfyUI_FL-MCP/backend/logs/fl_mcp_server.log
ComfyUI/custom_nodes/ComfyUI_FL-MCP/backend/logs/fl_mcp_client-<pid>.log
ComfyUI/custom_nodes/ComfyUI_FL-MCP/logs/fl_mcp_launcher.log

A write tool is disabled

This is expected. Turn on the narrowest matching gate under Ren → Settings → Bridge & safety, save, restart ComfyUI, run the action, then turn the gate off again when it is no longer needed.

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 --experimental-default-type=module --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:

Name		Name	Last commit message	Last commit date
Latest commit History 296 Commits
.github/workflows		.github/workflows
assets		assets
backend		backend
docs		docs
skills/workflow-assistant		skills/workflow-assistant
tests		tests
web/js		web/js
.comfyignore		.comfyignore
.gitignore		.gitignore
.variables.json		.variables.json
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
__init__.py		__init__.py
mcp_daemon.py		mcp_daemon.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Navigation Menu

Repository files navigation

ComfyUI FL-MCP

Demo

What It Does

Highlights

Installation

Manual Install

ComfyUI Desktop

Bridge settings

Quick Start

Model providers

Using the built-in chat

External MCP clients

Operating Modes

Assistant Data and Security

Safety Gates

Tool Inventory

API Endpoints

Common Workflows

Troubleshooting

Optional Agent Skill

Development

Support

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

ComfyUI FL-MCP

Demo

What It Does

Highlights

Installation

Manual Install

ComfyUI Desktop

Bridge settings

Quick Start

Model providers

Using the built-in chat

External MCP clients

Operating Modes

Assistant Data and Security

Safety Gates

Tool Inventory

API Endpoints

Common Workflows

Troubleshooting

Optional Agent Skill

Development

Support

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages