Fal Image Video Mcp

FAL 图像/视频 MCP 服务 🎨🎬

高性能 MCP 服务，支持 FAL AI 图像和视频生成，并自动下载生成内容

将 FAL AI 强大的图像和视频生成功能无缝接入 Claude 等兼容 MCP 的客户端。所有生成的内容都会自动下载到本地设备，同时提供公开 URL、数据 URL 和本地文件路径。

生成图像

生成视频

🚀 Claude Desktop 设置

快速设置

1. 获取 FAL API 密钥：fal.ai
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，如有需要可用于分享
• ✅ 大小限制，防止上下文溢出

---

✨ 功能

类别	功能
🎨 图像生成	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 Desktop）+ HTTP/SSE（Smithery/Web）
🔐 延迟身份验证	无需 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 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（高质量 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"
  }
}

✨ 智能功能：

• ✅ 21 个精选模型，均来自 FAL AI 平台
• ✅ 通用执行，支持任意 FAL 端点
• ✅ 自动下载到 ~/Downloads（可配置）
• ✅ 支持三种 URL（公共 URL + 数据 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 服务以进行测试或集成：

# 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 创意！🚀