Fal Image Video MCP

🚀 FAL圖像/視頻MCP服務器 🎨🎬

FAL圖像/視頻MCP服務器是一個高性能的服務器，可實現FAL AI圖像和視頻的生成，並支持自動下載功能。它能無縫連接FAL AI強大的圖像和視頻生成能力與MCP兼容的客戶端（如Claude），所有生成的內容都會自動下載到本地，同時提供公共URL、數據URL和本地文件路徑。

圖像生成示例

視頻生成示例

🚀 快速開始

Claude桌面端設置

快速設置

1. 從 fal.ai 獲取你的FAL API密鑰。
2. 將其添加到Claude桌面端配置中：

{
  "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桌面端的優化配置

{
  "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桌面端優化）。
• 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桌面端。

📥 自動下載

所有生成的內容都會自動保存到本地！

默認行為

• 圖像：以 .jpg 文件格式下載。
• 視頻：以 .mp4 文件格式下載。
• 位置：~/Downloads 文件夾（或自定義的 DOWNLOAD_PATH）。
• 命名：fal_{model}_{timestamp}_{index}.{ext}

針對Claude桌面端的優化響應

{
  "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": "為優化Claude桌面端，默認禁用數據URL"
  },
  "autoopen_settings": {
    "enabled": true,
    "note": "使用默認應用程序自動打開文件"
  }
}

為何此配置對Claude桌面端更優：

• ✅ 本地文件路徑：允許Claude直接訪問下載的圖像。
• ✅ 無大數據URL：避免上下文過載。
• ✅ 自動打開文件：使用默認應用程序立即顯示生成的內容。
• ✅ 公共URL：如有需要，可用於共享。
• ✅ 大小限制：防止上下文溢出。

✨ 主要特性

類別	特性
🎨 圖像生成	8種精選模型，包括Imagen 4、FLUX Kontext Pro、Ideogram V3
🎬 視頻生成	7種文本到視頻模型，包括Veo 3、Kling 2.1 Master、Pixverse V4.5
🔄 圖像到視頻	6種圖像到視頻模型，用於為靜態圖像添加動畫效果
📥 自動下載	所有內容自動保存到本地，支持自定義路徑
🔗 三重URL支持	公共URL、數據URL和本地文件路徑
🚀 通用執行	運行FAL註冊表之外的任何模型
🌐 多傳輸方式	stdio（Claude桌面端） + HTTP/SSE（Smithery/網頁）
🔐 延遲認證	無需API密鑰即可發現工具，使用時再進行認證
⚡ 性能	TypeScript實現，異步操作，錯誤處理

🚀 版本歷史

版本1.0.0

• ✅ 初始版本，集成FAL AI
• ✅ 使用Flux模型進行圖像生成
• ✅ 使用Minimax進行視頻生成
• ✅ 支持數據URL轉換，以實現MCP兼容性
• ✅ 支持TypeScript
• ✅ 支持NPX部署

即將推出

• 🔜 更多FAL模型
• 🔜 批量處理
• 🔜 增強的錯誤處理
• 🔜 性能優化

🏗️ 技術細節

組件	技術	用途
後端	TypeScript + Node.js	核心服務器實現
AI客戶端	@fal-ai/client	FAL API集成
MCP SDK	@modelcontextprotocol/sdk	符合MCP協議
傳輸	stdio / HTTP + SSE	多傳輸方式通信
構建系統	TypeScript編譯器	生產構建
部署	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（高質量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：在任何圖像到視頻模型中使用返回的圖像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（可配置）
• ✅ 三重URL支持（公共 + 數據 + 本地文件URL）
• ✅ 按類型自動分類
• ✅ 為每個模型動態生成工具
• ✅ 處理特定模型的參數

🎯 無限制

• 想使用註冊表中沒有的模型？使用 execute_custom_model
• 需要查看所有可用模型？使用 list_available_models
• 既想要精選體驗，又想要完全的靈活性？沒問題！

MCP服務器提供公共URL和數據URL，以實現與Claude和其他客戶端的最大兼容性。

響應格式

兩個工具都返回結構化的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桌面端）
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創造力！ 🚀