Fal Image Video MCP

🚀 FAL图像/视频MCP服务器 🎨🎬

FAL图像/视频MCP服务器是一个高性能的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": "Data URLs disabled by default for Claude Desktop optimization"
  },
  "autoopen_settings": {
    "enabled": true,
    "note": "Files automatically opened with default application"
  }
}

为何这对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进行视频生成。
• ✅ 用于MCP兼容的数据URL转换。
• ✅ 支持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：

{
  "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 文件。

🌐 联系信息

• GitHub
• 网站
• 邮箱

作者：Matthew Rogers - 为各地的MCP客户端带来AI创意！ 🚀