ComfyUI-MCP-Server - ComfyUI Model Context Protocol インテグレーション

[!NOTE] ⭐ このプロジェクトが気に入った、または役に立ったと感じられた場合は、プロジェクトに Star をお願いします。皆様のサポートが、私たちが改善を続ける原動力です！

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

本プロジェクトは Python と TypeScript の2つの独立した言語バージョンを提供しており、機能はほぼ同等です。必要に応じて選択できます。

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

📋 プロジェクト機能

本プロジェクトを通じて、ComfyUI に接続することで、AI アシスタント（Claude Desktop、Trae、Dify など）に強力なマルチメディア生成能力を与えることができます：

Related MCP server: ComfyUI-MCP-Server-Python

✨ プロジェクトの特徴

• 🔌 ワークフロー即ツール：ComfyUI のノードグラフを Agent が利用可能なツールに抽象化します。

• 🎛️ カスタムパラメータ公開：ワークフロー内で外部に公開するパラメータを正確に定義できます。AI の操作を公開された範囲内に限定することで、モデルの「幻覚」や誤操作を防ぎます。

• 🔧 ゼ口侵入の接続：ComfyUI 本体への変更や必要な各プラグインのインストールは不要です。デプロイ後すぐに接続でき、箱から出してそのまま使えます。

• 📥 カスタムワークフロのインポート：API 形式のワークフロ JSONファイルを見手動でインポートでき、検証を通過すると Agent にスグに利用可能になります。サーバーの再起動は不要です。

• 📂 アセット管理：ロ.path またはネトワーURL から自動でリソースを ComfyUI へアプロードできます。

• ⚡ ストリーミングと進行状況サポート：生成進捗のレポートをサポートします（Client/Host の対応が必要です）。

• 🌍 国際化（中英ウ）対応：中英文（zh-CN/en）の国际化対応を内蔵しています。

• 🧩 標準 MCP 対応：STDIO と StreamHTTP 両対応の通信プロトコルをフルサポート。

• 🔬 Skills サポート：プロジェクトのスキルマニアル SKILL.md が含まれており、Skills に対応した AI アシスタント向けに Skills を使用して深い最適化を行います。

詳しいは、なぜ選ばれるのか をご覧ください。

🧰 使用可能なツール集

AI エージェントは MCP プロトコルを介して、以下の組み込みツールを呼び出すことができます。

🏆 私たちが選ばれる理由？

詳しいは、私たちが選ばれる理由 をご覧ください。

🎬 デモ動画

デフォルト表示

下の画像をクリックしてデモ動画を視聴できます。

API_JSON 表示

下の画像をクリックして表示デモ動画を視聴できます。

🚀 クイックスタート

たった2ステップでプロジェクトを簡単に起動できます。

注意：インストールしてプロジェクトを起動した後、使用教程 をご覧ください。そうしないとワークフロー機能は使用できません。

事前準備（必須）

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

• Node.js 18+ [オ`フィシャルリンク]

• ComfyUI 0.9.1+ [公式リンク]

• MCP クライアント / AI Agent（例：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. 接続・プロジェクトの起動

お使いのニーズに合わせてトランスポート方式を選択し、プロジェクトを起動します：

[!TIP] MCP トランスポート機構

MCP プロトコルは現在、サーバー通信を実現する2つの標準方式トランスポートを定義しています：

• STDIO

• Streamable HTTP

本プロジェクトは両方に対応しています。お使いの MCP クライアントの能力に応じて選択してください。

あなたがこのサーバーを利用することが、関連法規約、および適用される法規範、基準、ガイドラインに準拠していることを知る責任はあなたにあります。

モード1：STDIO接続（Claude DeSktop などのローカル向け）

• MCPクライアントからの起動： 以下 の JSON（B）をコピーし、MCPクライアントのMCP設定にペーストして書き換えます。

  [!NMOTE]

  一部の MCP クライアントが MCPサーバーを設定方法では、[例] を参照。

  その他は環境変数に設定してください。パラメータの詳細は [環境変数環境] を参照。

  ComfyUI がクラウドで動作している場合は、以下 "SYNC_MODE" を "manual" に設定してください。 GXP4

• ターミナルから起動：

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

モード2：StreamHTTP 接続（ネットワーク / 分散利用に推奨）

• MCP クライアントから接続： StreamHTTP のプロジェクト設定は「[.env]」で指定されます。以下 の JSON で構成 する必要はありません。

  [!NTEN> 一部の MCP クライアントが MCP Server を設定する方法紹介.要

  現在 StreamHTTP をサポートする MCPクライアント/対応クライエントは少ないで、ニーズに応じて試用ください。

  がComfyUI がクラウド上で動いている場合は、[.env](./.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公式が提供するデバッグツールです。StreamHTTP を Inspector の接続方式として推奨します。

• プロジェクトのクローン

• 関連する依存関係のインストール

  G > GXP8

• StreamHTTP 接続のサーバーを起動：

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

• *Inspector を Linux 起動：

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

启动完了後、コンソール以のようなアドレスが表表れます。ブラウザにコピーして、デブッグツールを開始できます：

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

Inspector の登場後、ブラウザのページ参照作成：

　id="usage">

📖 利用チュートリアル

本プロジェクトでは、ComfyUI のワークフローに簡単ン・ターキングし、AI Agエンツが正確に識別・呼び出しができるようにします。以下2つの方法でワークフローを追加できます。

マーキングルール（必ず確認）

どの方法を利用しても、ワークフローに以下のマーキングノードを追加さなければいけません：

1. ツール名と機能説明を定義する（必須）

• 新しく PrimitiveNode（基 Adapter foundamental Node）または PriteStringMultiline（複数項目文字列）ノードを追加。**コネクトは不要です。

• そのノードのタイトルをダブルクリックし、==您的工作流名称== などに変更します。例：==生图-文生图==。注意：これは Agent が表示するツール名です。一意なることを確認してください。

• そのノードのテキストボックスに、このワークフローの機能説明を書いてください（例："这是一个基础文生图流程，适合生成在元图片。"）。説明が詳細であれば、AI の良い判断に役立ちます。

[!TIP] 自動フィルタ：本プロジェクトは、==Workflow Name== という形式のないワークフローを自動的に無視し、AI が安全な範囲の内外で動作しないようにしています。

2. 変更可能なパラメータを公開（任意）

• AI が指定のノード属性（例: 正のプロンプート、幅、高、乱数 seed）を編集できるよしたい場合は、そのパラメータを公開します。

• ターゲットノード（例: CLIP Text Encode (Prompt)) などを見つけます。

• タイトルをダブルクリックし、=>パラメータ説明 の形式（例 =>正向提示词 または =>生成的图片宽度）に変更します。

• 保存後、サーバーはこれを MCP ツールの可変ラメータとして自動解析し、呼出し時に要求に応じて値を入力できます。

[!TIP] 自動フィルター： 本プロジェクトでは、=> プレフィックスの付いていない不要なノードのパラメータなどを自動的に無視し、AI が安全定義された領域のみに操作を制限して、誤誘発を防止します。

方式1：ComfyUI のキャンバスで設定（推奨）

ComfyUI が動作中で、新しいワークフローの保存機能をサポートするユーザー向け：

1. ComfyUI で　上記マーキングルールに従ってノードを整理します。

2. コントロールパネルの Save (保存) をクリック。

   保存後、まず Queue Prompt (実行) を一度クリックして、ワークフローぬかりなく動作することを確認することをお勧めします。

3. ワークフローは、ComfyUI のユーザーデータディレクトリ（通常は userdata/workflows/）に保存されます。

4. ワークフローの有効タイミングは SYNC_MODE の設定によります：

   • timed モード（デフォルト）：MCP サーバーはバックグラウンドで定期的にポーリングし、新規保存されたワークフローを自動で検出し、自動検証に合格した後、即座に AI Agent 用ツールとしてマウントします。

   • manual モード：AI Agent がツールライブラリを呼び出すときだけオンデマンドスキャンが一度実行されます。

   • push モード（実験的な機能）：ComfyUI プラグインとの併用で、保存後すぐにサーバーへ消息プッシュされます。

方式2：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 モード：次回 Agent がワークフローをリクエスト又はツールを実行するときに動に読み込みます。

[!NOTE] タスクキューに例外/失敗タスクについて

このプロジェクトを使っている間、ComfyUI タスクキュー（Queue）に赤いエラー・ボックスが出たり、実行失敗のメッセージ表示が出ることがあります。これは、本 MCP サーバーがバジックで ComfyUI エンジンからワークフローのトポロジーとノードの合法性を静かに検証し、AI の呼び出しに適合するかどうか確認するためです。これは正常な現象であり、他の描画や AI の正常な運用に一切影響はありませんので、気にせずログ24時間おきに無視してください。

⚙️ 環境設定

[!TIP] 注意

下記は本サーバーの全環境設定パラメータとそれ対応する説明です。最初にこのセクションをお読みください。

下記環境設定パラメータのうち一部はまだ実装していません。無効のものは今後のスヶジュールで使用されます。

# =============================================================================
# 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

例

Claude 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)

   MCPとは？ - Model Context Protocol

2. JSON-RPC 2.0

   JSON-RPC 2.0仕様

3. WebSocket

   WebSocket API (WebSockets) - Web APIs | MDN

4. REST API

   REST APIについて - GitHub Docs

技術制約とセキュリティ

• 依存性: ComfyUI のネイティブ API と WebSocket に強く依存しており、ComfyUI 標準形式以外のグラフのインポートには対応していません。

• セキュリティ検証: 現在のバージョンには強力な認証メカニズム（Token/Auth）はありません。公网にはさらさないでください。本番環境では、HTTPS および追加のゲートウェイのアクセスコントロールを推奨します。

• リソー消費: 高並行呼び出しは ComfyUI ホスト上のビデオメモリ（OOM）オーバーフローを引き起こす可能性があります。AIシステム プロンプト内で、同時実行の頻度を制限してください。

ワークフロー検証の精度

本プロジェクトではワークフローの検証精度は3つのモードに分かれています：

検証方式

• 過去のタスクによる検証：実行済みで実行結果がSUCCESSの過去のタスクに基づいて検証します。

  • この方法では、モデルなどの中核部分に影響を与えることなク、ワークフロー実行の成功確率です。

• 初期性のワークフローでのみ: 過去のタスクがない、または過去のタスクの実行時刻がそのタスクの対応するワークフローの最新変更時刻より早いのワークフローに基づいて検証します。

  • この方法はワークフローに対して初期性検証のみを行います。ノード間の接続に異常がないことを保証しますが、ワークフロー全体の実行成功ことはありません。

  • 生成画像の成功確保、関連するワークフローを手動で実行することをご検討ください。ワークフロー全体が実行に成功た後、過去のタスクに対応する記録が生成され、以降はAIツールが履歴検証済みとして認識できます。

• 外部インポート：AI/ユーザー自身提供する API JSON ファイル。ワークフロー実行前には一切検証はなされ、ワークフロー全体の成功は保証されません。

  • この方法では一切検証を行いません。すべての検証はComfyUIバックエンがに委ねられます。API JSONファイルの形式、ノード、パラメータ範囲に問題がある場合、ComfyUIバックエンドがブロックし、対応するエラーメ示ー をり返します。

  • この方式は予な画像生成措置であり、上記の過去タスクでの画像生成、初期性のワークフローでの画像生成がどちらも検証できない場合に使用します。

😓 今後の計画

[!NOTE] 注意

プロジェクトの機能を積極的に拡張しております。ご提案があれば、遠慮なく Issue をお送りください!

• ワークフロー解析の強: よリー複雑なネスト型ノードと動的なパラメータ抽出をサポートします。

• クラウド・サーシス統合: 主流のComfyUI クラウド・ホステイング・プラットフォーム（認証と API マッピング）に適合します。

• 接続の最適化: StreamHTTP における切断への再接続メカニズムと状態の保持を実施します。

• 性能モニタ: リソース消費とタスク・キューを監視する可視化パネルを追加します。

• ComfyUI プラグイン: MCP サービスとシームレスに連携する ComfyUI プラグインを開発します。

🤝 コントリビューション

いつでもコントリビューションを踢迎しています。ぜひ Pull Request をお送りください。

コントリビューションガイド

1. プロジェクトをFork してください

2. フィーチャーブランチを作成してください

3. 変更をコミットしてください。

4. ブランチにプッシュしてください

5. Pull Request を開いてください

📄 ラセンス

このプロジェクトは MIT ラセンスの下に公開されています。詳細は、 LICENSE ファイルを参照してください。

このプロジェクトは純粋の三者的コミュニティによるオープンソースであり、ComfyUI 公式のプロジェクトではありません。 MtaBrain-Labs からイニシアティブを受けています。

📬 連絡先

(注記: 業務の都い合わせで、メールへの返信が遅れる場合。優先的に有事は GitHub Issues をご利用ください)

問題の提出

MtaBrain-Labs(metabrain0302@163.com)

主なコントリビュータ

TypeScript 版の作者：

Metabrain?(qfz376978@??? )

[![]をご覧ください。テスト]

Python 版の作者：

OldDeer(q149882198653@outlook.com)

以上にまとめます.

免責事項

[!WARNING] 責免任事

このプロジェクトは公認のウェブサイトを一切では持しておません。インターネット上で見わける当該サイトは非公式であり、このプロジェクト無関です。ご自身でリスとをご判断ください。

私たちは有料のサービスは一切提なしていません。まあ、TO使用量を目し、何かトラブルが起きあれとも、当組識は一切の責任を負いません。

(シールをご利用になる前には、コードの提出をご確認お願いします。)