Fal Image Video MCP

🚀 FAL Image/Video MCP Server 🎨🎬

FAL AIの画像およびビデオ生成に特化した高性能MCPサーバーで、生成されたコンテンツは自動的にダウンロードされます。

FAL AIの強力な画像およびビデオ生成機能と、ClaudeなどのMCP互換クライアントとのシームレスな橋渡しを行います。生成されたすべてのコンテンツは自動的にローカルマシンにダウンロードされ、同時にパブリックURL、データURL、ローカルファイルパスが提供されます。

画像生成の例

ビデオ生成の例

🚀 クイックスタート

クイックセットアップ

1. fal.ai からFAL APIキーを取得します。
2. 取得したAPIキーをClaude Desktopの設定に追加します。

{
  "mcpServers": {
    "fal-image-video": {
      "command": "npx",
      "args": ["-y", "fal-image-video-mcp"],
      "env": {
        "FAL_KEY": "YOUR-FAL-AI-API-KEY"
      }
    }
  }
}

設定ファイルの場所

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Claude Desktop用の最適化設定

{
  "mcpServers": {
    "fal-image-video": {
      "command": "npx",
      "args": ["-y", "fal-image-video-mcp"],
      "env": {
        "FAL_KEY": "YOUR-FAL-AI-API-KEY",
        "DOWNLOAD_PATH": "/custom/download/path",
        "ENABLE_DATA_URLS": "true",
        "MAX_DATA_URL_SIZE": "1048576",
        "AUTOOPEN": "false"
      }
    }
  }
}

環境変数の説明:

• FAL_KEY (必須): FAL AIのAPIキー
• DOWNLOAD_PATH (任意): カスタムのダウンロードディレクトリ (デフォルト: ~/Downloads)
• ENABLE_DATA_URLS (任意): データURLの有効化/無効化 (デフォルト: false、Claude Desktop用に最適化)
• MAX_DATA_URL_SIZE (任意): データURLの最大ファイルサイズ (バイト単位、デフォルト: 2MB)
• AUTOOPEN (任意): 生成されたファイルをデフォルトアプリケーションで自動的に開く (デフォルト: true、クロスプラットフォーム)

FAL APIキーの取得方法

1. fal.ai にアクセスし、アカウントを作成します。
2. APIキーのセクションに移動します。
3. 新しいAPIキーを生成します。
4. YOUR-FAL-AI-API-KEY を実際のキーに置き換えます。
5. Claude Desktopを再起動します。

📥 自動ダウンロード

生成されたすべてのコンテンツは自動的にローカルマシンに保存されます！

デフォルトの動作:

• 画像: .jpg ファイルとしてダウンロードされます。
• ビデオ: .mp4 ファイルとしてダウンロードされます。
• 保存場所: ~/Downloads フォルダ (またはカスタムの DOWNLOAD_PATH)
• ファイル名: fal_{model}_{timestamp}_{index}.{ext}

🎯 Claude Desktop最適化レスポンス:

{
  "images": [
    {
      "url": "https://fal-storage.../image.jpg",
      "localPath": "/Users/you/Downloads/fal_imagen4_2025-01-06T12-30-45-123Z.jpg",
      "width": 1024,
      "height": 1024
    }
  ],
  "download_path": "/Users/you/Downloads",
  "data_url_settings": {
    "enabled": false,
    "max_size_mb": 2,
    "note": "Data URLs disabled by default for Claude Desktop optimization"
  },
  "autoopen_settings": {
    "enabled": true,
    "note": "Files automatically opened with default application"
  }
}

Claude Desktopでの最適化理由:

• ✅ ローカルファイルパスにより、Claudeがダウンロードされた画像に直接アクセスできます。
• ✅ 大きなデータURLが不要で、コンテキストが圧迫されません。
• ✅ 自動ファイルオープンにより、生成されたコンテンツがデフォルトアプリケーションで即座に表示されます。
• ✅ パブリックURLがあり、必要に応じて共有できます。
• ✅ サイズ制限により、コンテキストオーバーフローが防止されます。

✨ 主な機能

🚀 バージョン履歴

バージョン1.0.0

• ✅ FAL AIとの統合を含む初期リリース
• ✅ Fluxモデルによる画像生成
• ✅ Minimaxによるビデオ生成
• ✅ MCP互換性のためのデータURL変換
• ✅ TypeScriptサポート
• ✅ NPXによるデプロイ準備完了

今後の予定

• 🔜 追加のFALモデル
• 🔜 バッチ処理
• 🔜 エラーハンドリングの強化
• 🔜 パフォーマンス最適化

🏗️ 技術アーキテクチャ

📖 ドキュメント

利用可能なツール

🎨 画像生成モデル (8種類利用可能)

サーバーはFAL AIから最新の利用可能なモデルを動的にロードします。現在利用可能なモデルは以下の通りです。

imagen4 - Imagen 4

Googleの最新のテキストベースの画像生成モデルで、高品質な画像を生成します。

{
  "tool": "imagen4",
  "arguments": {
    "prompt": "A photorealistic mountain landscape at golden hour",
    "image_size": "landscape_16_9"
  }
}

flux_kontext - FLUX Kontext Pro

最先端のプロンプト追従性と活版印刷生成機能を備えています。

{
  "tool": "flux_kontext",
  "arguments": {
    "prompt": "Modern logo design with the text 'AI Studio'",
    "num_inference_steps": 25
  }
}

ideogram_v3 - Ideogram V3

高度な活版印刷とリアルな出力を提供します。

{
  "tool": "ideogram_v3",
  "arguments": {
    "prompt": "Vintage poster with text 'Retro Café'",
    "negative_prompt": "blurry, low quality"
  }
}

recraft_v3 - Recraft V3

プロフェッショナルなデザインとイラストレーション機能を備えています。

{
  "tool": "recraft_v3",
  "arguments": {
    "prompt": "Minimalist icon design for a mobile app",
    "image_size": "square_hd"
  }
}

その他の利用可能なモデル:

• stable_diffusion_35 - Stable Diffusion 3.5 Large
• flux_dev - FLUX Dev (高品質の12Bパラメータモデル)
• hidream - HiDream I1 (高解像度生成)
• janus - Janus (マルチモーダル理解)

🎬 画像からビデオへの変換モデル (6種類利用可能)

kling_master_image - Kling 2.1 Master I2V

滑らかな動きを備えた高品質な画像からビデオへの変換を行います。

{
  "tool": "kling_master_image",
  "arguments": {
    "image_url": "https://example.com/landscape.jpg",
    "prompt": "Gentle wind blowing through the trees",
    "duration": 5
  }
}

pixverse_image - Pixverse V4.5 I2V

高度な画像からビデオへの変換機能を備え、高品質な出力を提供します。

{
  "tool": "pixverse_image",
  "arguments": {
    "image_url": "https://example.com/portrait.jpg",
    "prompt": "Person looking around and smiling",
    "aspect_ratio": "16:9"
  }
}

wan_pro_image - Wan Pro I2V

エフェクトを備えたプロフェッショナルな画像アニメーションを提供します。

{
  "tool": "wan_pro_image",
  "arguments": {
    "image_url": "https://example.com/scene.jpg",
    "prompt": "Camera slowly panning across the scene"
  }
}

その他の利用可能なモデル:

• hunyuan_image - Hunyuan I2V (オープンソース)
• vidu_image - Vidu I2V (高品質のアニメーション)
• luma_ray2_image - Luma Ray 2 I2V (最新のLuma)

📹 テキストベースのビデオ生成モデル (7種類利用可能)

veo3 - Veo 3

Google DeepMindの最新のビデオ生成モデルで、音声およびオーディオ機能を備えています。

{
  "tool": "veo3",
  "arguments": {
    "prompt": "A serene mountain lake with gentle ripples at sunrise",
    "duration": 10,
    "aspect_ratio": "16:9"
  }
}

kling_master_text - Kling 2.1 Master

滑らかな動きとシネマティックな品質を備えた高品質なテキストベースのビデオ生成を行います。

{
  "tool": "kling_master_text",
  "arguments": {
    "prompt": "A cat playing with a ball of yarn in slow motion",
    "duration": 6,
    "aspect_ratio": "16:9"
  }
}

pixverse_text - Pixverse V4.5

精密な制御機能を備えた高度なテキストベースのビデオ生成を行います。

{
  "tool": "pixverse_text",
  "arguments": {
    "prompt": "Ocean waves crashing on a rocky shore at sunset",
    "duration": 8
  }
}

luma_ray2 - Luma Ray 2

最新のLuma Dream Machineで、強化された機能を備えています。

{
  "tool": "luma_ray2",
  "arguments": {
    "prompt": "A field of flowers swaying in the breeze",
    "aspect_ratio": "16:9"
  }
}

その他の利用可能なモデル:

• magi - Magi (クリエイティブなビデオ生成)
• wan_pro_text - Wan Pro (プロフェッショナルなビデオエフェクト)
• vidu_text - Vidu Q1 (高品質のテキストベースのビデオ生成)

🔄 画像からビデオへのワークフロー

もちろんです！ 生成された画像をClaudeに戻し、ビデオ生成に利用することができます。以下はその手順です。

1. 任意の画像モデルを使用して画像を生成します。

{
  "tool": "imagen4",
  "arguments": {
    "prompt": "A majestic mountain landscape at sunset"
  }
}

2. 返された画像URLを任意の画像からビデオへの変換モデルで使用します。

{
  "tool": "kling_master_image",
  "arguments": {
    "image_url": "<URL_FROM_PREVIOUS_GENERATION>",
    "prompt": "Gentle clouds moving across the sky",
    "duration": 5
  }
}

🔧 高度なモデルシステム

このMCPサーバーは包括的なモデルアクセス機能を備えています。

📋 モデルの探索

list_available_models を使用して、レジストリ内のすべてのモデルを確認できます。

{
  "tool": "list_available_models",
  "arguments": {
    "category": "imageGeneration"
  }
}

🚀 汎用モデル実行

execute_custom_model を使用して、レジストリ外の任意のFALエンドポイントを実行できます。

{
  "tool": "execute_custom_model",
  "arguments": {
    "endpoint": "fal-ai/custom-model-name",
    "input_params": {
      "prompt": "Your custom prompt",
      "custom_param": "value"
    },
    "category_hint": "image"
  }
}

✨ スマートな機能:

• ✅ FAL AIプラットフォームからの21種類の選りすぐりのモデル
• ✅ 任意のFALエンドポイントの汎用実行機能
• ✅ ~/Downloads (設定可能) への自動ダウンロード
• ✅ 3種類のURLサポート (パブリック + データ + ローカルファイルURL)
• ✅ タイプ別の自動分類
• ✅ 各モデルの動的ツール生成
• ✅ モデル固有のパラメータハンドリング

🎯 制限なし:

• レジストリにないモデルを使用したい場合は、execute_custom_model を使用します。
• すべての利用可能なモデルを確認したい場合は、list_available_models を使用します。
• 選りすぐりのエクスペリエンスと完全な柔軟性の両方が必要な場合は、このサーバーが最適です！

このMCPサーバーは、Claudeやその他のクライアントとの最大限の互換性のために、パブリックURL と データURL の両方を提供します。

レスポンス形式

両方のツールは構造化されたJSON形式でレスポンスを返します。

• パブリックURL: 生成されたコンテンツへの直接リンク
• データURL: 直接埋め込み用のBase64エンコードされたデータURL
• メタデータ: 生成パラメータと寸法
• Claude互換形式: 会話ですぐに使用できる形式

レスポンスの例:

{
  "model": "fal-ai/flux/schnell",
  "prompt": "A majestic dragon...",
  "images": [
    {
      "url": "https://storage.googleapis.com/fal-flux-storage/...",
      "dataUrl": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
      "width": 1024,
      "height": 768
    }
  ],
  "metadata": {
    "image_size": "landscape_4_3",
    "num_inference_steps": 4,
    "guidance_scale": 3.5
  }
}

🔧 代替インストール方法

🌐 HTTPサーバーモード (スタンドアロンテスト用)

テストまたは統合のためにHTTPサーバーを起動する:

# 自動検出されたポートで起動 (デフォルト: 3000)
npx -y fal-image-video-mcp --http

# または環境変数でポートを指定する
PORT=8080 npx -y fal-image-video-mcp --http

# カスタムトランスポートフラグを使用する
MCP_TRANSPORT=http npx -y fal-image-video-mcp

HTTPエンドポイント:

• GET /health - サーバーのヘルスチェック
• GET /mcp - MCP通信のためのSSEエンドポイント
• POST /mcp - JSON-RPCメッセージのハンドリング

サーバーをテストする:

# ヘルスチェック
curl http://localhost:3000/health

# 利用可能なツールをリストする
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

🎯 HTTPモードでの認証

遅延ロードサポート:

• ✅ サーバーはFAL_KEYなしで起動できる (ツールの探索用)
• ✅ ツールが呼び出されたときにのみAPIキーが検証される
• ✅ 認証が不足している場合には明確なエラーメッセージが表示される

FAL_KEYを設定する:

# 環境変数を使用する
FAL_KEY=your-api-key npx fal-image-video-mcp --http

# またはデプロイメントプラットフォームで設定する
export FAL_KEY=your-api-key
npx fal-image-video-mcp --http

本番環境でのデプロイ例:

# Dockerfile
FROM node:18-slim
ENV FAL_KEY=your-api-key
ENV PORT=3000
RUN npx -y fal-image-video-mcp --http
EXPOSE 3000

📱 NPX (一度限りの使用)

# Stdioモード (Claude Desktop)
npx -y fal-image-video-mcp

# HTTPモード (テスト/Smithery)
npx -y fal-image-video-mcp --http

🔧 グローバルインストール

npm install -g fal-image-video-mcp

# 異なるモードで実行する
fal-image-video-mcp              # Stdioモード
fal-image-video-mcp --http       # HTTPモード

💻 ソースからのインストール

git clone https://github.com/RamboRogers/fal-image-video-mcp.git
cd fal-image-video-mcp
npm install
npm run build

# トランスポートを選択する
npm start                    # Stdioモード
npm start -- --http         # HTTPモード

📄 ライセンス

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

🌐 コンタクト

作成者: Matthew Rogers - あらゆる場所のMCPクライアントにAIの創造性をもたらします！ 🚀