mcp-flux-pro

FluxMCP

AceDataCloud プラットフォームを通じて、Flux を使用した AI 画像の生成と編集を行う Model Context Protocol（MCP） サーバーです。

Claude、Cursor、その他の MCP 対応クライアントから、Flux モデル（flux-dev、flux-pro、flux-kontext）を使って、美しい AI 画像を直接生成・編集できます。

機能

• 画像生成 - 6 種類の Flux モデルでテキストプロンプトから画像を生成します
• 画像編集 - コンテキストを考慮する Flux Kontext モデルで既存の画像を編集します
• タスク管理 - 非同期生成タスクの追跡と、複数タスクのステータス照会に対応します
• モデルガイド - モデル選択とプロンプト作成のガイダンスを内蔵しています
• 2 種類のトランスポート - stdio（ローカル）と HTTP（リモート／クラウド）モード
• Docker 対応 - K8s デプロイマニフェストを含むコンテナ化に対応しています
• セキュア - HTTP モードでは、リクエストごとに分離された Bearer トークン認証を使用します

ツール一覧

ツール	説明
flux_generate_image	Flux を使ってテキストプロンプトから AI 画像を生成します。
flux_edit_image	Flux とテキストプロンプトを使って既存の画像を編集します。
flux_list_models	利用可能な Flux モデルとその機能をすべて一覧表示します。
flux_list_actions	利用可能な Flux ツールとその用途をすべて一覧表示します。
flux_get_task	Flux 画像生成タスクのステータスと結果を照会します。
flux_get_tasks_batch	複数の Flux 画像生成タスクを一度に照会します。

接続方法：ホスト型 OAuth、API トークン、またはローカル stdio

ホスト型エンドポイントは https://flux.mcp.acedata.cloud/mcp です。MCP クライアントで次のいずれかの方法を選択してください。

方法	使用する場合	認証情報の設定
ホスト型 OAuth	クライアントがリモート MCP OAuth に対応している場合	URL のみを追加し、AceDataCloud にサインインしてアクセスを承認します。クライアント設定にトークンを貼り付ける必要はありません。
ホスト型 API トークン	クライアントで OAuth を完了できない場合、または明示的な連携用認証情報が必要な場合	Authorization: Bearer … ヘッダーで AceDataCloud API トークンを送信します。ローカルのシークレットストアまたは環境変数に保管してください。
ローカル stdio	クライアントがローカルの MCP プロセスを実行する場合	mcp-flux-pro をインストールし、そのプロセスに ACEDATACLOUD_API_TOKEN を渡します。この方法でも AceDataCloud API を呼び出します。

ホスト型サービスは OAuth メタデータと Dynamic Client Registration（DCR）を公開しています。DCR はクライアントアプリケーションを登録するものであり、API キーではありません。 OAuth でサインインすると、クライアントは発行された Bearer トークンを送信します。アカウントの API 認証情報を再利用または新規作成する場合があります。ブラウザーでサインインするには、引き続き AceDataCloud アカウントが必要です。ホスト型サービスは従量課金制の場合があります。実際に操作する前に、最新のサービスドキュメントと表示価格を確認してください。同じサーバーに OAuth ログインと固定の Authorization ヘッダーの両方を設定しないでください。

ホスト型 OAuth の例

• Claude と Claude Desktop のチャット： Customize → Connectors → Add custom connector でリモートカスタムコネクターを追加し、https://flux.mcp.acedata.cloud/mcp を入力して、サインインを選択します。Claude から OAuth クライアントの登録方法を尋ねられた場合は、Register automatically を選択します。同意手続きを完了してください。Claude Desktop のローカルな claude_desktop_config.json は別途設定が必要です。Claude コネクターガイド。
• Claude Code： claude mcp add --transport http --scope user flux https://flux.mcp.acedata.cloud/mcp を実行し、続いて claude mcp login flux を実行します。/mcp を確認してください。Claude Code MCP ガイド。
• Cursor： https://flux.mcp.acedata.cloud/mcp のみを指定してリモートサーバーを追加します。プロジェクト用には、以下のエントリーを <project>/.cursor/mcp.json に統合します。個人用には ~/.cursor/mcp.json を使用します。Cursor MCP ガイド。
• VS Code / Copilot： MCP: Add Server を実行し、HTTP を選択して https://flux.mcp.acedata.cloud/mcp を入力した後、ブラウザーでのサインインを完了します。新しいポータブルなワークスペース設定には <project>/.mcp.json を使用します。以下の VS Code 固有の形式では、<project>/.vscode/mcp.json またはユーザープロファイルを使用します。MCP: List Servers を確認してください。VS Code MCP のセットアップ。
• Codex： codex mcp add flux --url https://flux.mcp.acedata.cloud/mcp を実行し、続いて codex mcp login flux を実行します。ユーザー設定は ~/.codex/config.toml にあります。Codex 公式 MCP ガイド。

Cursor プロジェクト設定（OAuth）：

{
  "mcpServers": {
    "flux": {"url": "https://flux.mcp.acedata.cloud/mcp"}
  }
}

VS Code 固有のワークスペース設定（OAuth）：

{
  "servers": {
    "flux": {"type": "http", "url": "https://flux.mcp.acedata.cloud/mcp"}
  }
}

ホスト型 API トークン

1. Ace Data Cloud → Applications を開きます。サインインするか、先にアカウントを登録します。
2. General application を探します。まだ作成されていない場合は、Initialize General Application を選択します。一般キーではアカウントで利用できるサービスを使用できますが、専用アプリケーションのキーはそのサービスに限定されます。必要なサービス／モデルへのアクセスと現在の料金を確認してください。
3. アプリケーションカードから API Key をコピーするか、Keys / Manage Keys → Create を開いて、この連携用の別のキーを作成します。個別に無効化またはローテーションできるよう、判別しやすい名前を付けてください。
4. キーを作成する際は、Expiration Time、Set Usage Limitation、Allowed APIs を確認します。必要な制限のみを有効にし、呼び出す操作を許可してから Create をクリックし、キーリストからトークンをコピーします。タスクの照会権限では、生成の送信は許可されません。最初のリクエストを実行できる残高がアプリケーションにあることを確認してください。試用枠がある場合、その内容はアカウントに現在表示されているものに従います。
5. 引用符、空白、Bearer を含めず、トークンの値だけをコピーします。API Key／API Token フィールドには、この生の値を入力します。手動で設定する HTTP Authorization ヘッダーに限り、Bearer プレフィックスが必要です。platform-... のアカウント管理用トークンを生成 API キーの代わりに使うことはできません。

キーはクライアントの認証情報ストア、または以下に示す環境変数に保存してください。プロンプト、共有ワークフロー、スクリーンショット、Git コミットには絶対に含めないでください。認証に失敗した場合は、別のキーを作成する前に、コピーした値全体、アプリケーション／サービスへのアクセス、期限、使用制限、残高を確認してください。

固定の Bearer ヘッダーを使用すると OAuth がバイパスされます。ヘッダーが無効な場合は、ブラウザーでのサインインを試す前に削除してください。保存した認証情報は非公開にしてください。

Claude Code では、サーバーの追加時にシェルがトークンを展開します。保存されたユーザー MCP 設定は秘密情報として扱ってください。

export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
claude mcp add --transport http --scope user flux https://flux.mcp.acedata.cloud/mcp \
  --header "Authorization: Bearer $ACEDATACLOUD_API_TOKEN"

Claude Code のプロジェクト設定では、<project>/.mcp.json に変数参照を記述し、Claude Code の起動環境でその変数を設定します。

{
  "mcpServers": {
    "flux": {
      "type": "http",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${ACEDATACLOUD_API_TOKEN}"}
    }
  }
}

Cursor では、~/.cursor/mcp.json または未コミットのプロジェクト設定で、異なる環境変数の構文を使用します。

{
  "mcpServers": {
    "flux": {
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${env:ACEDATACLOUD_API_TOKEN}"}
    }
  }
}

VS Code では、MCP: Open User Configuration を実行し、このサーバーとマスクされた入力をマージします。${input:...} は VS Code のユーザー／ワークスペース形式用であり、Agent Host の .mcp.json 形式には移植できません。

{
  "inputs": [
    {"id": "acedata-flux-token", "type": "promptString", "description": "AceDataCloud API token", "password": true}
  ],
  "servers": {
    "flux": {
      "type": "http",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${input:acedata-flux-token}"}
    }
  }
}

Cline では、MCP 設定 UI または CLI ファイル ~/.cline/data/settings/cline_mcp_settings.json を使用します。リモートトランスポートの値は streamableHttp です。JetBrains AI Assistant では、Settings → Tools → AI Assistant → Model Context Protocol (MCP) からリモート URL を追加します。Zed では、OAuth の場合は URL のみを指定した context_servers エントリーを使用するか、ローカルの Bearer ヘッダーを追加します。これらのクライアントでは設定スキーマがそれぞれ異なるため、別のクライアントの JSON をコピーせず、最新の UI に従ってください。Cline · JetBrains · Zed。

ローカル stdio

パッケージをインストールし、ローカルプロセスに API トークンを設定します。

python -m pip install mcp-flux-pro
export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
mcp-flux-pro

Claude Desktop のローカル MCP では、開発者設定から開いたファイル（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）にこのエントリをマージします。uvx を使うには、uv が PATH に含まれている必要があります。

{
  "mcpServers": {
    "flux": {
      "command": "uvx",
      "args": ["mcp-flux-pro"],
      "env": {"ACEDATACLOUD_API_TOKEN": "YOUR_API_TOKEN"}
    }
  }
}

このユーザーレベルのファイルは非公開にしてください。セルフホスト HTTP では mcp-flux-pro --transport http --port 8000 を使用します。適切なネットワークおよび TLS 制御を行った場合にのみ公開してください。ローカル実行でも AceDataCloud API が呼び出されます。

サービスを利用する前の確認

1. https://flux.mcp.acedata.cloud/health が {"status":"ok"} を返す場合、確認できるのはエンドポイントへの到達性のみです。
2. MCP クライアントがツールを読み込むことを確認します。flux_list_models は参照用ツールであり、下流 API へのアクセスや残高は確認できません。
3. API を完全に確認する必要がある場合は、現在のサービスドキュメントと表示されている料金を確認したうえで、有効な入力を使って flux_generate_image を呼び出します。結果にタスク ID が含まれている場合は、終端状態の成功または失敗になるまで、同じ ID に対して flux_get_task を呼び出します。進捗を確認する目的だけで操作を再送信しないでください。

401 の場合は、クライアントが使用した認証経路と、トークンまたは OAuth セッションが有効かどうかを確認してください。403 は、アカウントの権限またはコンテンツモデレーションによる失敗を意味する場合があります。返されたエラーを確認してください。残高不足や下流サービスの障害については、それぞれ個別に原因を調査する必要があります。ツールが一覧に表示されていることや、タスクが送信されたことだけでは、結果の成功は保証されません。

利用可能なツール

ツール	説明
flux_generate_image	モデルを選択してテキストプロンプトから画像を生成します
flux_edit_image	テキストの指示に従って既存の画像を編集します
flux_get_task	1 件の生成タスクのステータスを確認します
flux_get_tasks_batch	複数のタスクのステータスを一度に確認します
flux_list_models	利用可能な Flux モデルと機能をすべて一覧表示します
flux_list_actions	すべてのツールとワークフローの例を表示します

利用可能なプロンプト

プロンプト	説明
flux_image_generation_guide	適切なツールとモデルを選ぶためのガイド
flux_prompt_writing_guide	効果的なプロンプトを作成するためのベストプラクティス
flux_workflow_examples	よく使われるワークフローのパターンと例

対応モデル

モデル	品質	速度	サイズ形式	最適な用途
flux-dev	良好	高速	ピクセル（256～1440px）	迅速なプロトタイピング
flux-pro	高	中速	ピクセル（256～1440px）	本番環境での使用
flux-kontext-pro	高	中速	アスペクト比	画像編集
flux-kontext-max	最高	低速	アスペクト比	複雑な編集
flux-2-flex	高	高速	アスペクト比	Flux 2 のバランスの取れた品質
flux-2-pro	より高い	中速	アスペクト比	Flux 2 の本番環境での使用
flux-2-max	最高	低速	アスペクト比	Flux 2 の最高品質
flux-2-klein	良好	高速	アスペクト比	Flux 2 の効率的な出力

使用例

画像を生成する

"Generate a photorealistic mountain landscape at golden hour"
→ flux_generate_image(prompt="...", model="flux-2-max", size="16:9")

画像を編集する

"Add sunglasses to the person in this photo"
→ flux_edit_image(prompt="Add sunglasses", image_url="https://...", size="1:1", model="flux-kontext-pro")

タスクのステータスを確認する

"What's the status of my generation?"
→ flux_get_task(task_id="...")

環境変数

変数	必須	デフォルト	説明
ACEDATACLOUD_API_TOKEN	はい（stdio）	—	AceDataCloud の API トークン
ACEDATACLOUD_API_BASE_URL	いいえ	https://api.acedata.cloud	API のベース URL
ACEDATACLOUD_OAUTH_CLIENT_ID	いいえ	—	OAuth クライアント ID（ホステッドモード）
ACEDATACLOUD_PLATFORM_BASE_URL	いいえ	https://platform.acedata.cloud	プラットフォームのベース URL
FLUX_REQUEST_TIMEOUT	いいえ	1800	リクエストのタイムアウト（秒）
MCP_SERVER_NAME	いいえ	flux	MCP サーバー名
LOG_LEVEL	いいえ	INFO	ログレベル

開発

セットアップ

git clone https://github.com/AceDataCloud/FluxMCP.git
cd FluxMCP
pip install -e ".[all]"
cp .env.example .env
# Edit .env with your API token

リントとフォーマット

ruff check .
ruff format .
mypy core tools main.py

テスト

# Unit tests
pytest --cov=core --cov=tools

# Skip integration tests
pytest -m "not integration"

# With coverage report
pytest --cov=core --cov=tools --cov-report=html

Git フック

git config core.hooksPath .githooks

API リファレンス

この MCP サーバーは AceDataCloud Flux API を使用します。

• POST /flux/images — 画像を生成または編集します
• POST /flux/tasks — タスクのステータスを照会します（単一または一括）

API ドキュメント全文：platform.acedata.cloud

ドキュメント

ドキュメント

ライセンス

MIT ライセンス — 詳細は LICENSE をご覧ください。

リンク

• AceDataCloud プラットフォーム
• MCP プロトコル
• Black Forest Labs の Flux
• PyPI パッケージ

FLUX 3 動画

t2v、i2v、v2v、または draft_enhance の request に構造化データを指定して、flux_generate_video を使用します。例：{"mode":"t2v","prompt":"Waves at sunset","duration":5,"resolution":"hd","generate_audio":false}。画像モードには keyframes が必要で、動画モードには start_video が必要です。ドラフトの高画質化では、プラットフォーム上で所有する draft_task_id を使用し、一時ドラフトキャッシュが引き続き利用可能である必要があります。

動画生成では、action=generate（デフォルト）と mode=t2v/i2v/v2v/draft_enhance を指定して POST /flux/videos を使用します。各生成モードで、それぞれ固有のフィールドを指定できます。ツールはデフォルトでタスク ID を非同期に返します。最終的な動画を取得するには flux_get_task を使用してください。同期的に待機するには、リクエストで async=false を設定します。