Replicate Flux MCP

Replicate Flux MCP

English | 中文

Replicate Flux MCPは、AI アシスタントが高品質な画像やベクターグラフィックを生成できるようにする、高度な Model Context Protocol（MCP）サーバーです。デフォルトでは、ラスター画像の生成にblack-forest-labs/flux-schnell、SVG 出力の生成にrecraft-ai/recraft-v3-svgを使用します。環境変数を使って、厳選された画像／SVG モデルを変更できます。また、画像ツールでは、組み込みの許可リストにあるモデルを、呼び出しごとにmodel_idで指定して変更することもできます。

📑 目次

• はじめにと統合
  • セットアップ手順
  • Cursor との統合
  • Claude Desktop との統合
  • Smithery との統合
• Glama.ai との統合
• Codex との統合
• 機能
• ドキュメント
  • 利用可能なツール
  • 利用可能なリソース
  • 利用可能なプロンプト
  • 構造化出力
  • 環境変数
• 開発
  • テスト
• 技術的な詳細
• トラブルシューティング
• コントリビューション
• ライセンス
• リソース
• 例

🚀 はじめにと統合

セットアップ手順

1. Replicate API トークンを取得する

   • Replicateに登録します
   • アカウント設定で API トークンを作成します

2. 統合方法を選択する

   • お好みの MCP クライアントに応じて、以下の統合方法のいずれかに従います

3. AI アシスタントに画像の生成を依頼する

   • 「夕暮れ時の静かな山の風景を生成できますか？」のように自然な言葉で依頼します
   • または、より具体的に「前景に夕焼けの色を映す湖がある、穏やかな山の風景を描いた画像を作成してください」と依頼します

4. 高度な機能を試す

   • パラメーター設定を変えて、生成結果をカスタマイズします
   • generate_svgを使った SVG 生成を試します
   • 画像の一括生成やバリエーション生成機能を使います

Cursor との統合

方法 1：mcp.json を使用する

1. プロジェクトディレクトリにある.cursor/mcp.jsonファイルを作成または編集します：

{
  "mcpServers": {
    "replicate-flux-mcp": {
      "command": "env REPLICATE_API_TOKEN=YOUR_TOKEN npx",
      "args": ["-y", "replicate-flux-mcp"]
    }
  }
}

2. YOUR_TOKENを実際の Replicate API トークンに置き換えます
3. Cursor を再起動して変更を適用します

方法 2：手動モード

1. Cursor を開き、Settings に移動します
2. 「MCP」または「Model Context Protocol」セクションに移動します
3. 「Add Server」または同等の項目をクリックします
4. 適切なフィールドに次のコマンドを入力します：

env REPLICATE_API_TOKEN=YOUR_TOKEN npx -y replicate-flux-mcp

5. YOUR_TOKENを実際の Replicate API トークンに置き換えます
6. 設定を保存し、必要に応じて Cursor を再起動します

Claude Desktop との統合

1. 設定ディレクトリにある mcp.json ファイルを作成または編集します。

{
  "mcpServers": {
    "replicate-flux-mcp": {
      "command": "npx",
      "args": ["-y", "replicate-flux-mcp"],
      "env": {
        "REPLICATE_API_TOKEN": "YOUR TOKEN"
      }
    }
  }
}

2. YOUR_TOKEN を実際の Replicate API トークンに置き換えます
3. Claude Desktop を再起動して変更を適用します

Smithery との統合

この MCP サーバーは Smithery 上のホスト型サービスとして利用できるため、独自のサーバーをセットアップせずに使用できます。

1. Smithery にアクセスし、アカウントをお持ちでない場合は作成します
2. Replicate Flux MCP サーバーのページ に移動します
3. 「Add to Workspace」をクリックして、サーバーを Smithery ワークスペースに追加します
4. Smithery ワークスペースの URL を使用するように、MCP クライアント（Cursor、Claude Desktop など）を設定します

MCP クライアントでの Smithery の使用方法について詳しくは、Smithery のドキュメントをご覧ください。

Glama.ai との統合

この MCP サーバーは Glama.ai 上のホスト型サービスとしても利用でき、ローカルでセットアップせずに使用する別の方法を提供します。

1. Glama.ai にアクセスし、アカウントをお持ちでない場合は作成します
2. Replicate Flux MCP サーバーのページに移動します
3. 「Install Server」をクリックして、サーバーをワークスペースに追加します
4. Glama.ai ワークスペースを使用するように MCP クライアントを設定します

詳しくは、Glama.ai MCP サーバーのドキュメントをご覧ください。

Codex との統合

サーバーを ~/.codex/config.toml に追加します。

[mcp_servers.replicate]
command = "npx"
args = ["-y", "replicate-flux-mcp"]
env = { REPLICATE_API_TOKEN = "your-replicate-api-token", REPLICATE_IMAGE_MODEL_ID = "your-image-model-id", REPLICATE_SVG_MODEL_ID = "your-svg-model-id" }
startup_timeout_sec = 30_000

必要に応じて env の値を置き換えてください。REPLICATE_IMAGE_MODEL_ID / REPLICATE_SVG_MODEL_ID を省略した場合、サーバーは画像に black-forest-labs/flux-schnell を、SVG に recraft-ai/recraft-v3-svg を使用します。

厳選されたツールでは、モデルの上書き値が組み込みの許可リストに照らして検証されます。

• 画像生成：black-forest-labs/flux-schnell、google/imagen-4、black-forest-labs/flux-kontext-pro、ideogram-ai/ideogram-v3-turbo、black-forest-labs/flux-1.1-pro、black-forest-labs/flux-dev
• SVG 生成：recraft-ai/recraft-v3-svg
• レガシーな run_model の追加モデル：minimax/video-01、luma/reframe-video、topazlabs/video-upscale、topazlabs/image-upscale、szcho/codeformer、tencentarc/gfpgan

🌟 特長

• 🖼️ 高品質な画像生成 — デフォルトでは Flux Schnell のラスター画像を生成し、環境変数およびツールごとに画像モデルを上書きできます。
• 🎨 ベクターグラフィックス — ロゴ、アイコン、図表向けの Recraft V3 SVG。
• 📊 バッチ処理 + バリエーション — N 個のプロンプトから N 枚の画像、または 1 つのプロンプトから N 個のバリエーション（シードベースまたはプロンプト修飾子ベース）を生成します。
• 🧩 任意の Replicate モデル — run_replicate_model を使うと、任意の owner/name[:version] 形式の参照を指定できます。また、get_model_schema で OpenAPI 入力スキーマを調べられます。REPLICATE_MODEL_ALLOWLIST による許可リストも任意で設定できます。
• 📦 構造化出力 — すべての generate_* ツールは、人が読みやすいコンテンツとともに機械可読な structuredContent を返します。出力はツールごとの outputSchema（URL、プロンプト、形式、アスペクト比、バリエーションごとのシードなど）に準拠します。
• ⏳ 進行状況の通知 — バッチ生成とバリエーション生成では、progressToken を介してオプトインしたクライアントに notifications/progress を送信するため、長時間の処理もブラックボックス化されません。
• 💬 厳選されたプロンプト — すぐに使える 5 つのプロンプトテンプレート（logo、portrait、svg-icon、product-shot、isometric-diagram）を、Claude Desktop のスラッシュメニューと Cursor の @ メニューで利用できます。
• 🏷️ 適切なツールアノテーション — readOnlyHint / destructiveHint / openWorldHint / idempotentHint が正しく設定されており、クライアントが安全性とコストを判断できます。
• 🪵 構造化ログ — サーバー側のエラーは stderr ではなく notifications/message を介して送信されます。
• 🔌 あらゆる MCP クライアントとの互換性 — MCP protocol 2025-11-25 に対応し、Claude Desktop、Cursor、Cline、Zed、および仕様に準拠するあらゆるクライアントで動作します。
• 🔍 生成履歴 — imagelist、svglist、predictionlist リソースから過去の実行を確認できます。

📚 ドキュメント

利用可能なツール

generate_image

設定済みの画像モデル（許可リストに登録されたもののみ）を使用して、テキストプロンプトに基づいて画像を生成します。

{
  prompt: string;                // Required: Text description of the image to generate
  model_id?: string;             // Optional: Override image model (allowlist only)
  seed?: number;                 // Optional: Random seed for reproducible generation
  go_fast?: boolean;             // Optional: Run faster predictions with optimized model (default: true)
  megapixels?: "1" | "0.25";     // Optional: Image resolution (default: "1")
  num_outputs?: number;          // Optional: Number of images to generate (1-4) (default: 1)
  aspect_ratio?: string;         // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  output_format?: string;        // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  output_quality?: number;       // Optional: Image quality (0-100) (default: 80)
  num_inference_steps?: number;  // Optional: Number of denoising steps (1-4) (default: 4)
  disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
  support_image_mcp_response_type?: boolean; // Optional: Return embedded image content when supported (default: true)
}

generate_multiple_images

設定済みの画像モデル（許可リストに登録されたもののみ）を使用して、プロンプトの配列に基づいて複数の画像を生成します。

{
  prompts: string[];             // Required: Array of text descriptions for images to generate (1-10 prompts)
  model_id?: string;             // Optional: Override image model (allowlist only)
  seed?: number;                 // Optional: Random seed for reproducible generation
  go_fast?: boolean;             // Optional: Run faster predictions with optimized model (default: true)
  megapixels?: "1" | "0.25";     // Optional: Image resolution (default: "1")
  aspect_ratio?: string;         // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  output_format?: string;        // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  output_quality?: number;       // Optional: Image quality (0-100) (default: 80)
  num_inference_steps?: number;  // Optional: Number of denoising steps (1-4) (default: 4)
  disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
  support_image_mcp_response_type?: boolean; // Optional: Return embedded image content when supported (default: true)
}

generate_image_variants

設定済みの画像モデル（許可リストに登録されたもののみ）を使用して、単一のプロンプトから同じ画像の複数のバリエーションを生成します。

{
  prompt: string;                // Required: Text description for the image to generate variants of
  model_id?: string;             // Optional: Override image model (allowlist only)
  num_variants: number;          // Required: Number of image variants to generate (2-10, default: 4)
  prompt_variations?: string[];  // Optional: List of prompt modifiers to apply to variants (e.g., ["in watercolor style", "in oil painting style"])
  variation_mode?: "append" | "replace"; // Optional: How to apply variations - 'append' adds to base prompt, 'replace' uses variations directly (default: "append")
  seed?: number;                 // Optional: Base random seed. Each variant will use seed+variant_index
  go_fast?: boolean;             // Optional: Run faster predictions with optimized model (default: true)
  megapixels?: "1" | "0.25";     // Optional: Image resolution (default: "1")
  aspect_ratio?: string;         // Optional: Aspect ratio (e.g., "16:9", "4:3") (default: "1:1")
  output_format?: string;        // Optional: Output format ("webp", "jpg", "png") (default: "webp")
  output_quality?: number;       // Optional: Image quality (0-100) (default: 80)
  num_inference_steps?: number;  // Optional: Number of denoising steps (1-4) (default: 4)
  disable_safety_checker?: boolean; // Optional: Disable safety filter (default: false)
  support_image_mcp_response_type?: boolean; // Optional: Return embedded image content when supported (default: true)
}

generate_svg

設定済みの SVG モデル（許可リストに登録されたもののみ）を使用して、テキストプロンプトに基づいて SVG／ベクター出力を生成します。

{
  prompt: string;                // Required: Text description of the SVG to generate
  size?: string;                 // Optional: Size of the generated SVG (default: "1024x1024")
  style?: string;                // Optional: Style of the generated image (default: "any")
                                // Options: "any", "engraving", "line_art", "line_circuit", "linocut"
}

prediction_list

Replicate から最近の予測の一覧を取得します。

{
  limit?: number;  // Optional: Maximum number of predictions to return (1-100) (default: 50)
}

get_prediction

特定の予測に関する詳細情報を取得します。

{
  predictionId: string;  // Required: ID of the prediction to retrieve
}

run_model

生の入力ペイロードを使用して、許可リストに登録された Replicate モデルを実行します（動画モデルや復元モデルに便利です）。

{
  model_id: string;                // Required: Replicate model id (allowlist only)
  input?: Record<string, unknown>; // Optional: Raw input payload for the model
}

run_replicate_model

owner/name[:version] の参照を指定して、Replicate でホストされている任意のモデルを実行します。用意されたツールの中に適切なものがない場合の代替手段として使用してください。入力形式がわからない場合は、まず get_model_schema を呼び出してください。

{
  model: string;                              // Required: 'owner/name' or 'owner/name:version'
  input: Record<string, unknown>;             // Required: Model input parameters
  prefer_wait?: number;                       // Optional: Seconds to block waiting for sync output (1-60, default 60)
  return_as?: "url" | "base64" | "both";      // Optional: How to return file outputs (default "url")
}

REPLICATE_MODEL_ALLOWLIST 環境変数に、呼び出しを許可するモデルをカンマ区切りの owner/name 形式で設定します。未設定の場合は、すべてのモデルが許可されます。設定済みで値が空の場合は、すべて拒否されます（サーバーはすべてを暗黙に許可するのではなく、安全側に倒して拒否します）。

get_model_schema

Replicate モデルの OpenAPI 入力スキーマと説明を取得します。これにより、run_replicate_model に適切なパラメーターを渡せます。

{
  model: string;  // Required: Replicate model reference in 'owner/name' form
}

利用可能なリソース

imagelist

設定済みの画像モデルで生成した画像の履歴を閲覧します。

svglist

設定済みの SVG モデルで生成した SVG 出力の履歴を閲覧します。

predictionlist

Replicate の予測履歴をすべて閲覧します。

利用可能なプロンプト

Claude Desktop のスラッシュメニューと Cursor の @ パレットに表示される、厳選されたテンプレートです。それぞれが適切なデフォルト値を設定し、関連する生成ツールに処理を委ねます。

プロンプト	説明	引数
logo	ブランド／製品のロゴ	brand, style?, palette?
portrait	写実的なポートレート	subject, mood?, lens?
svg-icon	単一のコンセプトを表すベクターアイコン	concept, style?
product-shot	スタジオで撮影した製品写真	product, surface?
isometric-diagram	アイソメトリックな技術イラスト	subject, emphasis?

構造化出力

すべての generate_* ツールは、人間が読める content（テキスト＋画像ブロック）と、ツールの outputSchema に一致する機械可読な structuredContent の両方を返します。

ツール	structuredContent の形式
generate_image	{ url, prompt, format, aspect_ratio, seed? }
generate_svg	{ url, prompt, size, style, svg? }
generate_multiple_images	{ images: [{ url, prompt }], format, aspect_ratio }
generate_image_variants	{ base_prompt, variation_mode, variants: [{ variant_index, url, prompt_used, seed? }], format, aspect_ratio }

MCP の構造化出力に対応したクライアントは、文章を解析せずに URL とメタデータを直接利用できます。

環境変数

変数	必須	目的
REPLICATE_API_TOKEN	はい	Replicate の API トークンです。未設定の場合、サーバーは直ちに終了します。
REPLICATE_IMAGE_MODEL_ID	いいえ	generate_image、generate_multiple_images、generate_image_variants、create_prediction で使用するデフォルトの厳選画像モデルを上書きします。値は組み込みの画像許可リストに含まれている必要があります。
REPLICATE_SVG_MODEL_ID	いいえ	generate_svg で使用するデフォルトの SVG モデルを上書きします。値は組み込みの SVG 許可リストに含まれている必要があります。
REPLICATE_MODEL_ALLOWLIST	いいえ	run_replicate_model を制限する、カンマ区切りの owner/name エントリです。未設定 = すべてのモデルを許可します。設定済みで空 = すべて拒否します（フェイルクローズ）。プロセス起動時に一度だけ評価されるため、後から読み込む dotenv ではなく、MCP クライアントの env ブロックに設定してください。

💻 開発

1. リポジトリをクローンします：

git clone https://github.com/awkoy/replicate-flux-mcp.git
cd replicate-flux-mcp

2. 依存関係をインストールします：

npm install

3. TypeScript ウォッチャーを起動します：

npm run watch

4. プロジェクトをビルドします：

npm run build

5. MCP Inspector でサーバーのスモークテストを実行します：

npm run inspector

6. クライアントに接続します：

{
  "mcpServers": {
    "image-generation-mcp": {
      "command": "npx",
      "args": [
        "/Users/{USERNAME}/{PATH_TO}/replicate-flux-mcp/build/index.js"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "YOUR REPLICATE API TOKEN"
      }
    }
  }
}

テスト

このプロジェクトには現在、自動テストスイートがありません。検証は以下の方法で行います：

• npm run build — TypeScript の型チェックにより、ほとんどのリグレッションを検出できます。
• npm run inspector — ビルド済みバイナリを公式 MCP Inspector で実行し、ツール、リソース、プロンプトのエンドツーエンドのスモークテストを行います。

適切なテストフレームワーク（例：Vitest と MCP stdio クライアントのハーネス）を追加する貢献を歓迎します。

⚙️ 技術詳細

スタック

• Model Context Protocol SDK - ツールとリソースを管理する MCP の中核機能
• Replicate API - 最先端の AI 画像生成モデルを利用できます
• TypeScript - 型安全性を確保し、最新の JavaScript 機能を活用します
• Zod - 堅牢な API 連携のためのランタイム型検証を実装します

設定

src/config/index.ts の CONFIG オブジェクトを変更するか、環境変数 REPLICATE_IMAGE_MODEL_ID / REPLICATE_SVG_MODEL_ID を設定してデフォルトを上書きすることで、サーバーを設定できます：

export const CONFIG = {
  serverName: "replicate-flux-mcp",
  serverVersion: "0.4.1",
  imageModelId: process.env.REPLICATE_IMAGE_MODEL_ID ?? "black-forest-labs/flux-schnell",
  svgModelId: process.env.REPLICATE_SVG_MODEL_ID ?? "recraft-ai/recraft-v3-svg",
  pollingAttempts: 25,
  pollingInterval: 2000, // ms
  modelAllowlistConfigured: process.env.REPLICATE_MODEL_ALLOWLIST !== undefined,
  modelAllowlist: (process.env.REPLICATE_MODEL_ALLOWLIST ?? "")
    .split(",")
    .map((s) => s.trim())
    .filter(Boolean),
};

モデルの切り替え（コード変更なし）

サーバーの起動時に環境変数を使用します（npx、Cursor、Claude Desktop などで利用できます）。厳選画像／SVG ツールの上書き先は、組み込みの許可リストに含まれている必要があります：

# Stay on defaults:
REPLICATE_API_TOKEN=YOUR_TOKEN npx -y replicate-flux-mcp

# Switch to other allowlisted models
REPLICATE_IMAGE_MODEL_ID="google/imagen-4" \
REPLICATE_SVG_MODEL_ID="recraft-ai/recraft-v3-svg" \
REPLICATE_API_TOKEN=YOUR_TOKEN \
npx -y replicate-flux-mcp

modelAllowlist は、プロセス起動時に REPLICATE_MODEL_ALLOWLIST から一度だけ評価されます。変更後はサーバーを再起動してください。

🔍 トラブルシューティング

よくある問題

認証エラー

• REPLICATE_API_TOKEN が環境に正しく設定されていることを確認してください
• Replicate API に直接問い合わせて、トークンが有効であることを確認してください

セーフティフィルターが作動する

• モデルには特定のプロンプトをブロックするセーフティフィルターが組み込まれています
• 問題となる可能性のある内容を避けるように、プロンプトを変更してみてください

タイムアウトエラー

• 大きな画像やサーバーの混雑時には、設定の pollingAttempts または pollingInterval を増やす必要がある場合があります
• デフォルト設定は、ほとんどのユースケースで機能するはずです

🤝 貢献

貢献を歓迎します！以下の手順に従ってください：

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

機能のリクエストやバグ報告は、GitHub issue を作成してください。このプロジェクトを気に入っていただけたら、リポジトリにスターを付けてください！

📄 ライセンス

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

🔗 リソース

• Model Context Protocol のドキュメント
• Replicate API のドキュメント
• 無料で試せるコレクション
• Flux Schnell モデル
• Recraft V3 SVG モデル
• MCP TypeScript SDK
• Smithery のドキュメント
• Glama.ai の MCP サーバー
• 作者：Yaroslav Boiko

🎨 例

複数のプロンプト	プロンプトのバリエーション

ツールの使用例を紹介します。

generate_multiple_images による画像の一括生成

異なるプロンプトを使って、一度に複数の個別の画像を作成します。

{
  "prompts": [
    "A red sports car on a mountain road", 
    "A blue sports car on a beach", 
    "A vintage sports car in a city street"
  ]
}

generate_image_variants による画像のバリエーション生成

シードを使って、同じコンセプトをさまざまに解釈した画像を作成します。

{
  "prompt": "A futuristic city skyline at night",
  "num_variants": 4,
  "seed": 42
}

または、プロンプトに修飾語を加えてスタイルのバリエーションを試せます。

{
  "prompt": "A character portrait",
  "prompt_variations": [
    "in anime style", 
    "in watercolor style", 
    "in oil painting style", 
    "as a 3D render"
  ]
}

---

Yaroslav Boiko が ❤️ を込めて作成