Fal Image Video Mcp

FAL Image/Video MCP Server 🎨🎬

自動ダウンロード機能を備えた、FAL AI の画像・動画生成用高性能 MCP サーバー

FAL AI の強力な画像・動画生成機能と、Claude などの MCP 対応クライアントをシームレスにつなぎます。生成したコンテンツはすべて、パブリック URL、データ URL、ローカルファイルパスを提供しながら、ローカルマシンに自動ダウンロードされます。

画像を作成

動画を作成

🚀 Claude Desktop のセットアップ

クイックセットアップ

1. fal.ai から FAL API キーを取得します
2. 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も利用できます
• ✅ サイズ制限により、コンテキストのオーバーフローを防ぎます

---

✨ 機能

カテゴリ	機能
🎨 画像生成	Imagen 4、FLUX Kontext Pro、Ideogram V3 を含む厳選された 8 つのモデル
🎬 動画生成	Veo 3、Kling 2.1 Master、Pixverse V4.5 を含むテキストから動画を生成する 7 つのモデル
🔄 画像から動画へ	静止画像をアニメーション化する、画像から動画を生成する 6 つのモデル
📥 自動ダウンロード	カスタムパスに対応し、すべてのコンテンツをローカルに自動保存
🔗 3 種類の URL に対応	パブリック URL、データ URL、ローカルファイルパス
🚀 あらゆるモデルを実行	厳選されたレジストリ以外の FAL モデルも実行
🌐 複数のトランスポートに対応	stdio（Claude Desktop）＋ HTTP/SSE（Smithery/Web）
🔐 遅延認証	API キーなしでツールを検出し、使用時に認証
⚡ パフォーマンス	TypeScript による実装、非同期処理、エラー処理

---

🚀 バージョン履歴

Version 1.0.0

• ✅ FAL AI 統合による初回リリース
• ✅ Flux モデルによる画像生成
• ✅ Minimax による動画生成
• ✅ MCP 互換性のためのデータ URL 変換
• ✅ TypeScript に対応
• ✅ NPX でのデプロイに対応

近日公開予定

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

---

🏗️ 技術アーキテクチャ

コンポーネント	テクノロジー	目的
バックエンド	TypeScript + Node.js	コアサーバーの実装
AI クライアント	@fal-ai/client	FAL API の統合
MCP SDK	@modelcontextprotocol/sdk	MCP プロトコルへの準拠
トランスポート	stdio / HTTP + SSE	複数のトランスポートによる通信
ビルドシステム	TypeScript Compiler	本番ビルド
デプロイ	npm / Docker / Smithery	複数のデプロイ方法

---

📖 使用方法

利用可能なツール

🎨 画像生成モデル（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（高品質な 120 億パラメーターのモデル）
• 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 + データ 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 サーバーを起動します：

# Start on auto-detected port (default: 3000)
npx -y fal-image-video-mcp --http

# Or specify port via environment
PORT=8080 npx -y fal-image-video-mcp --http

# With custom transport flag
MCP_TRANSPORT=http npx -y fal-image-video-mcp

HTTP エンドポイント：

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

サーバーをテストします：

# Health check
curl http://localhost:3000/health

# List available tools
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 を設定します：

# Via environment variable
FAL_KEY=your-api-key npx fal-image-video-mcp --http

# Or configure in your deployment platform
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 mode (Claude Desktop)
npx -y fal-image-video-mcp

# HTTP mode (Testing/Smithery)
npx -y fal-image-video-mcp --http

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

npm install -g fal-image-video-mcp

# Run in different modes
fal-image-video-mcp              # Stdio mode
fal-image-video-mcp --http       # HTTP mode

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

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

# Choose your transport
npm start                    # Stdio mode
npm start -- --http         # HTTP mode

---

📄 ライセンス

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

---

🌐 つながる

Matthew Rogers が作成 - あらゆる場所の MCP クライアントに AI の創造性を届けます！ 🚀