comfyui-mcp-server

ComfyUI-MCP-Server - ComfyUI Model Context Protocol 統合

[简体中文] [英語]

メモ

⭐ このプロジェクトを気に入ったり、役に立つと感じたりした場合は、ぜひ Star を付けてください。皆さまのご支援が、継続的な改善の原動力です！

ComfyUI-MCP-Server は、MCP（Model Context Protocol／モデルコンテキストプロトコル）に基づくサーバー実装です。ComfyUI でユーザーが定義したワークフローを、パラメーターを設定できる MCP ツールに変換し、AI エージェント（Agents）が直接利用できるようにします。

本プロジェクトには Python と TypeScript の独立した 2 つの言語バージョンがあり、機能はほぼ同等です。必要に応じてお選びください。

注：Python バージョンには、より多くの実験的機能が含まれています。TypeScript バージョンは、より安定しています。

📋 プロジェクトの機能

本プロジェクトを通じて ComfyUI に接続すると、Claude Desktop、Trae、Dify などの AI アシスタントに、強力なマルチメディア生成機能を追加できます。

✨ プロジェクトの特長

• 🔌 ワークフローをツールに：ComfyUI のノードグラフを、エージェントが利用できるツールとして抽象化します。
• 🎛️ カスタムパラメーターの公開：ワークフロー内で外部に公開するパラメーターを正確に定義できます。AI の操作範囲を公開したパラメーターに限定することで、モデルのハルシネーションや誤操作を防ぎます。
• 🔧 非侵襲的な連携：ComfyUI 本体の変更や必須プラグインのインストールは不要です。デプロイするだけで接続でき、すぐに使い始められます。
• 📥 カスタムワークフローのインポート：API 形式のワークフロー JSON ファイルを手動でインポートできます。検証後すぐにエージェントから利用でき、サービスの再起動も不要です。
• 📂 アセット管理：ローカルパスまたはネットワーク URL から、リソースを ComfyUI に自動アップロードできます。
• ⚡ ストリーミングと進捗状況のサポート：生成の進捗状況を報告できます（クライアント／ホスト側の対応が必要です）。
• 🌍 多言語対応：中国語と英語（zh-CN/en）に対応しています。
• 🧩 標準 MCP への対応：STDIO と Streamable HTTP の通信プロトコルを全面的にサポートしています。
• 🔬 Skills 対応：プロジェクトのスキルガイドSKILL.mdを収録しています。Skills に対応した AI アシスタント向けに、Skills を通じて高度に最適化されています。

詳細は当プロジェクトを選ぶ理由をご覧ください。

🧰 利用可能なツール

AI エージェントは、MCP プロトコルを通じて以下の組み込みツールを呼び出せます。

🏆 当プロジェクトが選ばれる理由

詳細については、当プロジェクトが選ばれる理由をご覧ください。

🎬 デモ動画

デフォルト方式

下の画像をクリックすると、デモ動画を視聴できます。

API_JSON 方式

下の画像をクリックすると、デモ動画を視聴できます。

🚀 クイックスタート

2つの手順で、すぐにプロジェクトを起動できます。

注意：プロジェクトをインストールして起動した後、ワークフロー関連機能を使用するには、[使用方法]も確認してください。

事前準備（必須）

本プロジェクトを起動する前に、以下のソフトウェアがシステムにインストールされていることを確認してください。

• Node.js 18+ [公式リンク]
• ComfyUI 0.9.1+ [公式リンク]
• MCP クライアント／AI エージェント（Claude Desktop、Cursor など）

ステップ1：プロジェクトと依存関係のインストール

1. 本プロジェクトをクローンする ターミナルで以下のコマンドを実行します。

git clone https://github.com/MetaBrain-Labs/ComfyUI-MCP-Server-TypeScript.git

2. プロジェクトディレクトリに移動する

cd ComfyUI-MCP-Server-TypeScript

3. 依存関係をインストールする

npm install

ステップ2：環境を設定してプロジェクトを起動する

1. プロジェクト環境の設定

プロジェクトのルートディレクトリに移動し、システムの実際の状況に合わせて .env ファイル内の設定を変更します。 詳しい設定については、[環境変数]をご覧ください。

2. 连接并运行项目

根据您的需求选择传输方式以启动项目：

ヒント

MCP传输机制

MCP 协议目前定义了两种客户端-服务器通信的标准传输机制：

• STDIO
• Streamable HTTP

本项目两者皆支持，请根据您的 MCP 客户端能力进行选择。

您有责任确保使用这些服务器符合相关条款，以及适用于您的任何法律、规则、法规、政策或标准。

模式一：STDIO 连接 (推荐用于 Claude Desktop 等本地客户端)

• MCP客户端启动： 复制下述 JSON 文件，在 MCP 客户端的 MCP 配置中粘贴并修改即可。

  メモ

  部分 MCP 客户端配置 MCP Server 的方法请查阅：[示例]

  其他项目设置请在环境变量中修改，参数详情请查阅：[环境变量]

  如果 ComfyUI 在云端运行，请将 "SYNC_MODE" 设置为 "manual"

  {
    "mcpServers": {
      "comfy-ui-advanced": {
        "command": "npx",
        "args": [
          "tsx",
          "<项目根目录绝对路径，如 D:/ComfyUI-MCP-Server-TypeScript>"
        ],
        "env": {
          "LOCALE": "en",
          "MCP_SERVER_URL": "http://127.0.0.1:8189/mcp",
          "MCP_SERVER_IP": "127.0.0.1",
          "MCP_SERVER_PORT": "8189",
          "COMFY_UI_SERVER_IP": "http://127.0.0.1:8188",
          "COMFY_UI_SERVER_HOST": "127.0.0.1",
          "COMFY_UI_SERVER_PORT": "8188",
          "SYNC_MODE": "timed",
          "SYNC_POLL_INTERVAL_SECONDS": "3",
          "SYNC_EVENT_FALLBACK_INTERVAL_SECONDS": "300",
          "ONDEMAND_REFRESH_COOLDOWN_SECONDS": "3",
          "COMFY_UI_INSTALL_PATH": "",
          "WORKFLOW_NAME_REGEX": "^==(.+?)==$",
          "WORKFLOW_PARAM_REGEX": "^=>(.+)$",
          "LOG_LEVEL": "INFO"
        }
      }
    }
  }
  

• 终端启动：

  # 终端连接启动方式无需配置json，直接在项目根目录下执行：
  npm run dev
  

模式二：StreamHTTP 连接 (推荐用于网络化/分布式部署)

• MCP客户端启动： StreamHTTP 的项目设置在 [.env] 中指定，无需在下述 JSON 中配置。

  メモ

  部分 MCP 客户端配置 MCP Server 的方法请查阅：[示例]

  目前支持 StreamHTTP 的 MCP Client/Host 较少，请根据需求使用。

  如果 ComfyUI 在云端运行，请在 [.env] 中将 "SYNC_MODE" 设置为 "manual"

  {
    "mcpServers": {
      "comfy-ui-advanced-http": {
        "url": "http://127.0.0.1:8189/mcp"
      }
    }
  }
  

• 终端启动：

  # 启动 Streamable HTTP
  npm run dev
  

至此，项目部署且启动完成。若您需要调试工具，请继续阅读下文，否则请直接跳转至[使用教程]。

调试工具 (MCP Inspector)

Inspector是MCP官方提供的MCP调试工具，推荐使用StreamHTTP作为Inspector的连接方式。

• 克隆项目
• 安装相关依赖

  npm install
  

• 启动StreamHTTP连接方式的Server：

  # 1. 在终端 A 启动 HTTP 服务
  npm run dev
  

• 启动Inspector：

  # 2. 在终端 B 启动 Inspector
  npm run inspector
  

启动完成后，控制台中会出现类似下述地址，复制地址到浏览器后即可开始调试相关工具：

# 每次启动MCP_PROXY_AUTH_TOKEN都不一样，因此每次启动后需要及时切换链接
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=d66fcf6cbbb3723c60bfef51f020e5e96811002a675e7162b065b44f2fe377f3

inspector启动成功后，浏览器页面配置参考：

📖 使用教程

本项目需要对 ComfyUI 工作流进行简单的特定标记，以使 AI Agent 能够准确识别和调用，可以通过以下两种方式添加可用工作流：

标记规则（必须了解）

无论使用哪种方式添加可用工作流，都必须在其工作流中添加以下标记节点：

1. 定义工具名称与功能描述（必须）

• 新建一个 PrimitiveNode (基础节点) 或 PrimitiveStringMultiline (多行字符串节点)，无需与任何节点连线。
• 双击修改节点标题为 ==您的工作流名称==（例：==生图-文生图==）。注意：这是 AI Agent 将看到的工具名，必须确保唯一。
• 在该节点的文本输入框中，写下这段工作流的功能描述（例："这是一个基础文生图流程，适合生成二次元图片"）。描述越清晰，AI 越能准确判断何时调用。

ヒント

自动过滤： 本项目会自动忽略没有 ==Workflow Name== 格式的工作流，确保 AI 只在划定的安全范围内操作，避免模型幻觉。

2. 暴露可自主修改的参数（可选）

• 如果您希望 AI 可以动态修改某些节点属性（例如：正向提示词、长宽尺寸、随机种子），需要暴露其参数。
• 找到目标节点（如：CLIP Text Encode (Prompt) 节点）。
• 双击修改其标题为 =>参数描述（例：=>正向提示词 或 =>生成的图片宽度）。
• 保存后，本服务器会自动将其解析为 MCP 工具的可变参数，AI 调用时将能按需填入值。

ヒント

自动过滤： 本项目会自动忽略没有 => 标题前缀的其它全部常规节点参数及节点连接相关参数，确保 AI 只在划定的安全范围内操作，避免模型幻觉。

方式一：在 ComfyUI 画布中设置（推荐）

适用于正在运行 ComfyUI 且支持新版工作流保存机制的用户：

1. 在 ComfyUI 中按照上述标记规则整理好节点。
2. 点击 ComfyUI 面板上的 Save (保存) 按钮。

   建议在保存后，先自行点击一次 Queue Prompt (运行) 测试，确保工作流能够正常跑通。

3. 工作流将被保存至 ComfyUI 的用户数据目录（通常为 userdata/workflows/）。
4. 工作流生效时间视 SYNC_MODE 配置而定：
   • timed 模式（默认）：MCP 服务器会在后台定时轮询，自动发现新保存的工作流，并在自动校验通过后立即挂载成 AI Agent 可用的工具。
   • manual 模式：仅当 AI Agent 尝试调用工具库时才触发一次按需扫描。
   • push 模式（实验性功能）：需配合 ComfyUI 插件，可实现保存后实时主动推送到服务器。

方式二：手动导入 API 格式 JSON 文件

适用于外部导入工作流或直接编写纯 API 格式（API Format）的工作流文件：

1. 准备好您的 ComfyUI API 格式 JSON 文件。

2. 使用文本编辑器打开该 JSON 文件，添加以下内容以符合核心标记规则：

   • 工具名称： 在任意位置添加以下内容：

    "99": {
      "inputs": {
        "value": "**功能描述**"
      },
      "class_type": "PrimitiveStringMultiline",
      "_meta": {
        "title": "==工作流名称=="
      }
    }
   

   "99" 仅为示例，实际使用时请使用未被占用的节点 ID。
   添加完毕后请检查json格式是否正确，每个节点后都需添加逗号，否则将导致工作流无法使用。

   • 暴露参数： 找到需要让 AI 修改的参数所在的节点，添加或修改 _meta 对象中的 "title": "=>参数描述"。

3. 将修改后的 JSON 文件直接放入本项目的 workflow/ 目录下（如果该目录不存在，请手动创建）。

4. 工作流生效机制与上述相同，依据 SYNC_MODE 模式：

   • timed 模式（默认）：MCP 服务器将定时扫描该目录，自动解析参数并完成挂载。
   • manual / push 模式：工作流将在 AI Agent 下次请求工作流或执行工具时按需加载生效。

メモ

关于任务队列中出现错误/失败任务的说明

在使用本项目期间，ComfyUI 任务队列（Queue）中可能会偶尔出现报错红框或提示失败的任务。这是因为本 MCP 服务器需要在后台通过 ComfyUI 引擎静默校验您的工作流拓扑及节点合法性，以验证其是否适合供 AI 调用。这属于正常现象，完全不会影响其他绘图和 AI 的正常工作，请放心忽略。

⚙️ 环境配置

ヒント

注意

下列是本服务器的全部环境配置参数以及对应的介绍，请优先阅读此。

下列环境配置参数中部分还未启用，未启动的均为后续计划中使用的。

# =============================================================================
# ComfyUI MCP Server - Configuration
# 配置文件说明：
#   [User Config]   用户配置 —— 根据您的部署环境修改此区块
#   [System Config] 系统配置 —— 保持默认即可，无需修改
# =============================================================================

# =============================================================================
# [User Config] 用户配置
# Modify this section based on your deployment environment.
# 根据您的部署环境修改以下内容。
# =============================================================================

# Language for MCP tool descriptions.
# MCP 工具描述的显示语言。可选值：en（英文）| zh（中文）
LOCALE=en

# -----------------------------------------------------------------------------
# ComfyUI Server Connection / ComfyUI 服务器连接
# -----------------------------------------------------------------------------

# Full URL of your ComfyUI server. No trailing slash.
# ComfyUI 服务器的完整地址，末尾不加斜杠。
COMFY_UI_SERVER_IP="http://192.168.0.171:8188"

# Host (without protocol) and port. Used separately for WebSocket connections.
# 主机名（不含协议头）和端口号，WebSocket 连接时单独使用。
COMFY_UI_SERVER_HOST="192.168.0.171"
COMFY_UI_SERVER_PORT="8188"

# -----------------------------------------------------------------------------
# Sync Mode / 同步模式
# -----------------------------------------------------------------------------

# Controls how the server detects workflow updates from ComfyUI.
# 控制服务器检测 ComfyUI 工作流更新的方式。
#
#   timed  — Background loop polls ComfyUI at a fixed interval. (default)
#             后台循环以固定间隔轮询 ComfyUI。（默认）
#
#   push   — [Experiments] ComfyUI plugin sends real-time save events; long fallback poll as safety net.
#             Requires COMFY_UI_INSTALL_PATH (must be on same machine as ComfyUI).
#            [实验性功能] ComfyUI 插件实时推送保存事件；兜底长轮询作为安全网。
#             需要配置 COMFY_UI_INSTALL_PATH（需与 ComfyUI 同机部署）。
#
#   manual — No background loop. Refresh only when tools are called
#             (get_workflows_catalog / mount_workflow / queue_prompt).
#             无后台循环，仅在调用工具时按需刷新
#             （get_workflows_catalog / mount_workflow / queue_prompt）。
#
SYNC_MODE=timed

# Polling interval in seconds for timed mode.
# timed 模式的轮询间隔（秒）。
SYNC_POLL_INTERVAL_SECONDS=3

# Fallback polling interval in seconds for push mode (safety net for missed events).
# push 模式的兜底轮询间隔（秒），用于捕捉遗漏的推送事件。
SYNC_EVENT_FALLBACK_INTERVAL_SECONDS=300

# Cooldown in seconds between manual mode refreshes.
# Prevents excessive ComfyUI API calls when tools are called in quick succession.
# manual 模式两次刷新之间的冷却时间（秒），防止工具短时间内连续调用时频繁请求 ComfyUI API。
ONDEMAND_REFRESH_COOLDOWN_SECONDS=30

# -----------------------------------------------------------------------------
# Push Mode Plugin / 推送模式插件（仅 SYNC_MODE=push 时需要）
# -----------------------------------------------------------------------------

# Absolute path to your LOCAL ComfyUI installation root directory.
# Required when SYNC_MODE=push: MCP Server will automatically deploy a lightweight
# backend plugin that pushes workflow save events in real-time.
# Leave blank if ComfyUI runs on a remote machine or if using timed/manual mode.
#
# 本地 ComfyUI 安装目录的绝对路径。
# 使用 SYNC_MODE=push 时必填：MCP Server 会自动部署一个超轻量推送插件，
# 实现工作流保存后的实时推送通知。
# 若 ComfyUI 部署在远端机器上，或使用 timed/manual 模式，请留空。
#
# Windows 示例 / Example: COMFY_UI_INSTALL_PATH=C:/ComfyUI
# Linux   示例 / Example: COMFY_UI_INSTALL_PATH=/home/user/ComfyUI
COMFY_UI_INSTALL_PATH=

# -----------------------------------------------------------------------------
# Workflow Marker Patterns / 工作流标识符正则表达式
# -----------------------------------------------------------------------------

# Regex identifying the workflow name node (title of a PrimitiveStringMultiline node).
# Must contain ONE capture group that extracts the MCP tool name.
# Default matches titles like "==my_workflow=="
# 工作流名称节点的标识正则（PrimitiveStringMultiline 节点的 title）。
# 必须含一个捕获组提取工具名，默认匹配 ==名称== 格式。
WORKFLOW_NAME_REGEX=^==(.+?)==$

# Regex identifying configurable parameter nodes.
# Must contain ONE capture group that extracts the parameter description.
# Default matches titles like "=>prompt text"
# 参数节点的标识正则，必须含一个捕获组提取参数描述，默认匹配 =>描述 格式。
WORKFLOW_PARAM_REGEX=^=>(.+)$

# =============================================================================
# [System Config] 系统配置
# Internal settings — change only if you know what you are doing.
# 内部运行参数，通常无需修改。
# =============================================================================

# -----------------------------------------------------------------------------
# MCP Server / MCP 服务地址
# -----------------------------------------------------------------------------

# MCP server bind address and listening port.
# MCP 服务器的监听地址和端口（MCP 客户端连接此处）。
MCP_SERVER_URL="http://192.168.0.192:8189/mcp"
MCP_SERVER_IP="192.168.0.192"
MCP_SERVER_PORT="8189"

# -----------------------------------------------------------------------------
# Logging / 日志配置
# -----------------------------------------------------------------------------

# Minimum log level written to stderr.
# 输出到 stderr 的最低日志级别。
# DEBUG | INFO | WARNING | ERROR  (default: INFO)
LOG_LEVEL=INFO

# Optional absolute path for a log file.
# When set, logs are written to BOTH stderr and this file.
# Leave blank to disable file logging.
# 可选：日志文件的绝对路径。填写后同时输出到 stderr 和文件。留空则不开启文件日志。
# LOG_FILE=

# Log file rotation size. Default: 10 MB
# 日志文件切割大小，默认 10 MB。
# LOG_ROTATE=10 MB

# Number of rotated log files to retain. Default: 7
# 保留历史日志文件个数，默认 7。
# LOG_RETAIN=7

示例

Cluade Desktop

点击下方图片观看演示视频。

Trae

下の画像をクリックして、デモ動画をご覧ください。

🛠️ トラブルシューティング

よくある問題

1. WebSocket 接続に失敗する
   • ComfyUI が実行中であることを確認してください。
   • ComfyUI の WebSocket ポート設定を確認してください。
   • .env の COMFY_UI_SERVER_HOST と PORT が正しく設定されていることを確認してください。
2. ワークフローの実行に失敗する
   • 提出したパラメーターの型が、対象ノードの要件（Schema）と一致していることを確認してください。
   • ComfyUI のコンソールにカスタムノード（Custom Nodes）の不足に関するエラーがないか確認してください。
   • MCP Client/Host に対応する MCP Server のログを確認し、詳細なエラー情報を取得してください。
3. セッションの有効期限切れ
   • HTTP セッションのデフォルトのタイムアウト時間は 30 分です。非常に長時間の動画レンダリングを行う場合は、コード内の SESSION_TIMEOUT 定数を変更して延長できます。

🔬 技術的な詳細

コアプロトコル

1. MCP (Model Context Protocol)

   What is the Model Context Protocol (MCP)? - Model Context Protocol

2. JSON-RPC 2.0

   JSON-RPC 2.0 Specification

3. WebSocket

   The WebSocket API (WebSockets) - Web APIs | MDN

4. REST API

   About the REST API - GitHub Docs

技術的な制限とセキュリティ上の考慮事項

• 依存性：ComfyUI ネイティブ API と WebSocket に強く依存しており、ComfyUI 標準以外の形式のグラフのインポートには対応していません。
• セキュリティ認証：現バージョンでは強力な認証メカニズム（Token/Auth）は実装されていません。インターネットに公開した状態で実行しないでください。本番環境では、HTTPS と追加のゲートウェイ層によるアクセス制御を設定することを推奨します。
• リソース消費：高頻度の同時呼び出しにより、ComfyUI ホストの VRAM が不足（OOM）する可能性があります。AI システムプロンプトで同時リクエストの頻度を制限してください。

ワークフロー検証の精度

本プロジェクトでは、ワークフロー検証の精度を次の 3 つのモードに分類しています。

• 履歴タスクによる検証：実行が完了し、実行結果が SUCCESS である履歴タスクに基づいて検証します。
  • この方法では、モデルなどの中核要素に影響がない場合に、ワークフローの実行成功率を確保できます。
• 初期ワークフローのみで検証：履歴タスクがない場合、または履歴タスクの実行時刻が対応するワークフローの最新の変更時刻より前の場合に、ワークフローに基づいて検証します。
  • この方法ではワークフローの初期検証のみを行います。ノード間の接続に異常がないことを確認しますが、ワークフロー全体が正常に実行されることは保証しません。
  • 画像生成の成功率を高めるには、該当するワークフローを手動で実行することを検討してください。ワークフロー全体の実行が成功すると、履歴タスクに対応するタスク記録が作成され、以後 AI ツールは履歴タスクによる検証に合格したものとして認識できます。
• 外部インポート：AI／ユーザーが独自に提供した API JSON ファイルです。ワークフローの実行前に検証は行われず、ワークフロー全体が正常に実行されることは保証されません。
  • この方法では一切検証を行わず、すべての検証を ComfyUI バックエンドに委ねます。API JSON ファイルの形式、ノード、パラメーター範囲などに問題がある場合、ComfyUI バックエンドが処理を拒否し、対応するエラー情報を返します。
  • この方法は画像生成の最後の手段です。上記の履歴タスクによる画像生成と初期ワークフローによる画像生成のどちらも利用できない場合に使用します。

🗺️ 今後の計画

ヒント

注意

プロジェクトの機能を積極的に拡張しています。良い提案があれば、Issue をぜひご提出ください！

• ワークフロー解析の強化：より複雑なネストされたノードと動的パラメーターの抽出に対応します。
• クラウドサービスとの統合：主要な ComfyUI クラウドホスティングプラットフォームに対応します（認証と API マッピング）。
• 接続の最適化：StreamHTTP での切断後の再接続メカニズムと状態保持を改善します。
• パフォーマンスパネル：リソース使用量とタスクキューの状態を可視化して表示します。
• ComfyUI プラグイン：ComfyUI プラグインを開発し、MCP サービスとのシームレスな統合を実現します。

🤝 貢献

貢献を歓迎します！いつでも Pull リクエストをご提出ください。

貢献ガイド

1. プロジェクトを Fork します
2. 機能ブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. Pull Request を作成します

📄 ライセンス

本プロジェクトは MIT ライセンスに基づくオープンソースです。詳細は LICENSE ファイルをご覧ください。

本プロジェクトは第三者コミュニティによるオープンソースの取り組みであり、ComfyUI の公式製品ではありません。MetaBrain-Labs の支援により開発されています。

📬 お問い合わせ

(注：業務の都合上、メールへの返信が遅れる場合があります。GitHub Issues を優先してご利用ください)

問題／要望の提出

MetaBrain-Labs([email protected])

コントリビューター

TypeScript 版の作者：

LaiFQZzr([email protected])

Python 版の作者：

OldDeer([email protected])

免責事項

警告

免責事項

現在、公式ウェブサイトはありません。インターネット上で見つかる関連ウェブサイトは、いずれも非公式であり、本オープンソースプロジェクトとは関係ありません。リスクを各自でご判断ください。

また、有料サービスは一切提供していません。TOKEN の使用状況にご注意ください。発生した損失について、当組織は一切責任を負いません。