Pixelle Mcp

🏃‍♂️ クイックスタート

ニーズに最適なデプロイ方法を、シンプルなものから複雑なものまで選択してください。

🎯 方法 1: ワンクリックで試す

💡 設定不要で起動でき、手早く試したりテストしたりするのに最適です

🚀 一時実行

# First you need to install the uv environment
# Start with one command, no system installation required
uvx pixelle@latest

📚 uvx CLI リファレンスを見る →

📦 継続的に使用するためのインストール

# Here you need to install it in the python3.11 environment
# Install to system
pip install -U pixelle

# Start service
pixelle

📚 pip CLI リファレンスを見る →

起動後、自動的に設定ウィザードが表示され、実行エンジンの選択（ComfyUI／RunningHub）と LLM の設定に進みます。

🛠️ 方法 2: ローカル開発環境へのデプロイ

💡 カスタムワークフローと二次開発に対応します

📥 1. ソースコードを取得

git clone https://github.com/AIDC-AI/Pixelle-MCP.git
cd Pixelle-MCP

🚀 2. サービスを起動

# Interactive mode (recommended)
uv run pixelle

📚 CLI リファレンス全体を見る →

🔧 3. カスタムワークフローを追加（任意）

# Copy example workflows to data directory (run this in your desired project directory)
cp -r workflows/* ./data/custom_workflows/

⚠️ 重要: まず ComfyUI でワークフローをテストし、正常に実行できることを確認してください。確認しないと実行に失敗します。

🐳 方法 3：Docker によるデプロイ

💡 本番環境やコンテナ化されたデプロイに適しています

📋 1. 設定を準備する

git clone https://github.com/AIDC-AI/Pixelle-MCP.git
cd Pixelle-MCP

# Create environment configuration file
cp .env.example .env
# Edit .env file to configure your ComfyUI address and LLM settings

🚀 2. コンテナを起動する

# Start all services in background
docker compose up -d

# View logs
docker compose logs -f

🌐 サービスへのアクセス

どの方法を使用した場合も、起動後は以下からアクセスできます。

• 🌐 Web インターフェース：http://localhost:9004
  デフォルトのユーザー名とパスワードはどちらも dev です。起動後に変更できます。
• 🔌 MCP エンドポイント：http://localhost:9004/pixelle/mcp
  Cursor、Claude Desktop などの MCP クライアントが接続するために使用します。

💡 ポートの設定：デフォルトのポートは 9004 です。環境変数 PORT=your_port で変更できます。

⚙️ 初期設定

初回起動時、システムは設定状況を自動的に検出します。

1. 🚀 実行エンジンの選択：ローカルの ComfyUI または RunningHub クラウドサービスを選択します
2. 🤖 LLM の設定：少なくとも 1 つの LLM プロバイダー（OpenAI、Ollama など）を設定します
3. 📁 ワークフローディレクトリ：システムが必要なディレクトリ構造を自動的に作成します

🌐 RunningHub クラウドモードのメリット

• ✅ ハードウェア要件なし：ローカル GPU や高性能なハードウェアは不要です
• ✅ 環境構築不要：ComfyUI をローカルにインストールして設定する必要はありません
• ✅ すぐに利用可能：登録して API キーを取得すれば、すぐに利用を開始できます
• ✅ 安定したパフォーマンス：プロフェッショナルなクラウドインフラストラクチャにより、安定した実行を実現します
• ✅ 自動スケーリング：同時リクエストとリソース割り当てを自動的に処理します

🏠 ローカル ComfyUI モードのメリット

• ✅ 完全な制御：実行環境とモデルのバージョンを完全に制御できます
• ✅ プライバシー保護：すべてのデータ処理がローカルで行われるため、データのプライバシーを保護できます
• ✅ カスタムモデル：クラウドでは利用できないカスタムモデルやノードをサポートします
• ✅ ネットワーク接続不要：インターネット接続なしでオフライン利用できます
• ✅ コスト管理：高頻度で利用してもクラウドサービス料金はかかりません

🆘 お困りですか？ サポートについてはコミュニティグループに参加してください（下記の「コミュニティ」セクションを参照）

🛠️ 独自の MCP ツールを追加する

⚡ 1 つのワークフローが 1 つの MCP ツールになります。次の 2 つの追加方法に対応しています。

📋 方法 1：ローカル ComfyUI ワークフロー - API 形式のワークフローファイルをエクスポートします
📋 方法 2：RunningHub ワークフロー ID - クラウドのワークフロー ID をそのまま使用します

🎯 1. 最も簡単な MCP ツールを追加する

• 📝 ComfyUI で画像にガウスぼかしを適用するワークフローを作成します（こちらから取得）。以下に示すように、LoadImage ノードのタイトルを $image.image! に設定します。

• 📤 API 形式のファイルとしてエクスポートし、i_blur.json に名前を変更します。自分でエクスポートすることも、事前にエクスポートされたファイルを使用することもできます（こちらから取得）。

• 📋 エクスポートした API ワークフローファイル（API 形式である必要があります）をコピーして Web ページに入力し、LLM にこのツールを追加させます。

  

• ✨ 送信すると、LLM がこのワークフローを自動的に MCP ツールに変換します。

  

• 🎨 その後、ページを更新して任意の画像を送信すると、LLM を介してガウスぼかしを適用できます。

  

🔌 2. 複雑な MCP ツールを追加する

手順は上記と同じで、ワークフローの部分だけが異なります（ワークフローをダウンロード：UI 形式 および API 形式）。

注： RunningHub を使用する場合は、対応するワークフロー ID を入力するだけでよく、ワークフローファイルのダウンロードやアップロードは不要です。

🔧 ComfyUI ワークフローのカスタム仕様

🎨 ワークフロー形式

このシステムは ComfyUI ワークフローに対応しています。キャンバスでワークフローを設計し、API 形式でエクスポートするだけです。ノードのタイトルに特別な構文を使用して、パラメーターと出力を定義します。

📝 パラメーター定義の仕様

ComfyUI のキャンバスでノードのタイトルをダブルクリックして編集し、以下の DSL 構文を使用してパラメーターを定義します。

$<param_name>.[~]<field_name>[!][:<description>]

🔍 構文の説明：

• param_name：生成される MCP ツール関数のパラメーター名
• ~：省略可能です。URL パラメーターのアップロード処理を示し、相対パスを返します
• field_name：ノード内の対応する入力フィールド
• !：このパラメーターが必須であることを示します
• description：パラメーターの説明

💡 例：

必須パラメーターの例：

• LoadImage ノードのタイトルを次のように設定します：$image.image!:Input image URL
• 意味：image という名前の必須パラメーターを作成し、ノードの image フィールドに割り当てます

URL アップロード処理の例：

• 任意のノードのタイトルを次のように設定します：$image.~image!:Input image URL
• 意味：image という名前の必須パラメーターを作成します。システムが URL を自動的にダウンロードして ComfyUI にアップロードし、相対パスを返します

📝 注：LoadImage、VHS_LoadAudioUpload、VHS_LoadVideo などのノードには機能が組み込まれているため、~ マーカーを追加する必要はありません

🎯 型推論ルール

システムはノードフィールドの現在の値に基づいて、パラメーターの型を自動的に推論します：

• 🔢 int：整数値（例：512、1024）
• 📊 float：浮動小数点値（例：1.5、3.14）
• ✅ bool：ブール値（例：true、false）
• 📝 str：文字列値（デフォルトの型）

📤 出力定義の仕様

🤖 方法 1：出力ノードを自動検出する

システムは、以下の一般的な出力ノードを自動的に検出します：

• 🖼️ SaveImage - 画像保存ノード
• 🎬 SaveVideo - 動画保存ノード
• 🔊 SaveAudio - 音声保存ノード
• 📹 VHS_SaveVideo - VHS 動画保存ノード
• 🎵 VHS_SaveAudio - VHS 音声保存ノード

🎯 方法 2：出力を手動で指定する

通常、複数の出力がある場合に使用します 任意のノードのタイトルで $output.var_name を使用して出力を指定します：

• ノードのタイトルを次のように設定します：$output.result
• システムは、このノードの出力をツールの戻り値として使用します

📄 ツールの説明の設定（任意）

ワークフローに MCP というタイトルのノードを追加すると、ツールの説明を設定できます：

1. String (Multiline) または同様のテキストノードを追加します（文字列プロパティが 1 つだけあり、ノードフィールドが次のいずれかである必要があります：value、text、string）
2. ノードのタイトルを MCP に設定します
3. 値フィールドにツールの詳細な説明を入力します

⚠️ 重要な注意事項

1. 🔒 パラメーターの検証：省略可能なパラメーター（! が付いていないもの）には、ノードでデフォルト値を設定する必要があります
2. 🔗 ノードの接続：すでに他のノードに接続されているフィールドは、パラメーターとして解析されません
3. 🏷️ ツール名：エクスポートしたファイル名がツール名として使用されるため、意味のある英語名を使用してください
4. 📋 詳細な説明：ユーザー体験を向上させるため、パラメーターを詳しく説明してください
5. 🎯 エクスポート形式：API 形式でエクスポートする必要があります。UI 形式ではエクスポートしないでください