fal.ai MCP Server

fal.ai MCP 服务

用于与 fal.ai 模型和服务交互的模型上下文协议（MCP）服务。

功能

• 列出所有可用的 fal.ai 模型
• 按关键字搜索特定模型
• 获取模型架构
• 使用任意 fal.ai 模型生成内容
• 支持直接执行和队列执行模型
• 队列管理（检查状态、获取结果、取消请求）
• 将文件上传到 fal.ai CDN

要求

• Python 3.10+
• fastmcp
• httpx
• aiofiles
• fal.ai API 密钥

安装

手动安装（推荐）

1. 克隆此仓库：

git clone https://github.com/am0y/mcp-fal.git
cd mcp-fal

2. 创建虚拟环境并安装依赖项：

python -m venv venv
venv/Scripts/pip install -r requirements.txt  # Windows
# OR
venv/bin/pip install -r requirements.txt      # Linux/Mac

3. 将 fal.ai API 密钥设置为环境变量：

export FAL_KEY="YOUR_FAL_API_KEY_HERE"

Docker 安装（实验性）

1. 克隆此仓库：

git clone https://github.com/am0y/mcp-fal.git
cd mcp-fal

2. 复制环境模板并添加 API 密钥：

cp .env.example .env
# Edit .env and add your fal.ai API key

3. 启动服务：

docker-compose up -d

使用方法

重要

用于 MCP 集成（VS Code、Claude Desktop、Antigravity）

✅ 使用选项 2（直接执行 Python）——这是正确且推荐的方式。

❌ 请勿使用 Docker——MCP 服务使用 stdio 传输，必须由 MCP 客户端启动。由于没有 stdin 连接，Docker 容器会立即退出。

说明

为什么 Docker 不适用于 MCP

MCP 服务通过标准输入/输出（stdio）进行通信。它们设计为由 MCP 客户端作为子进程启动，而非作为独立服务运行。尝试在 Docker 中运行 MCP 服务时，服务启动后会发现没有 stdin 连接，并立即退出。

---

选项 1：虚拟环境设置（推荐用于 MCP 集成）

前提条件：已安装 Python 3.10+

步骤 1：创建虚拟环境

# Create virtual environment
python -m venv venv

# Activate it (optional, for manual testing)
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

步骤 2：安装依赖项

# Windows
venv/Scripts/pip install -r requirements.txt

# Linux/Mac
venv/bin/pip install -r requirements.txt

步骤 3：设置 API 密钥

在项目根目录中创建 .env 文件：

cp .env.example .env

编辑 .env 并添加 fal.ai API 密钥：

FAL_KEY=your_actual_fal_api_key_here

---

选项 2：在本地测试服务

用于本地测试和开发（MCP 集成无需此操作）：

FastMCP 开发模式

启动 MCP Inspector Web 界面，以交互方式测试工具：

fastmcp dev main.py

直接执行

直接运行服务（将等待 stdio 输入）：

venv/Scripts/python main.py  # Windows
venv/bin/python main.py      # Linux/Mac

---

MCP 集成配置

完成上述虚拟环境设置后，配置 MCP 客户端：

对于 Claude Desktop

编辑 %APPDATA%\Claude\claude_desktop_config.json（Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json（Mac）：

{
    "mcpServers": {
        "fal": {
            "command": "d:/Projects/python/mcp-fal/venv/Scripts/python.exe",
            "args": ["d:/Projects/python/mcp-fal/main.py"],
            "env": {
                "FAL_KEY": "your_fal_api_key_here"
            }
        }
    }
}

对于 VS Code/Antigravity（MCP 设置）：

{
    "mcpServers": {
        "fal": {
            "command": "d:/Projects/python/mcp-fal/venv/Scripts/python.exe",
            "args": ["d:/Projects/python/mcp-fal/main.py"],
            "env": {
                "FAL_KEY": "your_fal_api_key_here"
            }
        }
    }
}

对于 Linux/Mac，使用：

{
    "mcpServers": {
        "fal": {
            "command": "/absolute/path/to/mcp-fal/venv/bin/python",
            "args": ["/absolute/path/to/mcp-fal/main.py"],
            "env": {
                "FAL_KEY": "your_fal_api_key_here"
            }
        }
    }
}

要点：使用虚拟环境中的 Python 解释器（Windows 上为 venv/Scripts/python.exe，Linux/Mac 上为 venv/bin/python），以确保所有依赖项均可用。

安全提示：不要将 API 密钥硬编码在配置中，你可以：

1. 将 FAL_KEY 设置为系统环境变量
2. 在配置中使用 "FAL_KEY": "${env:FAL_KEY}" 来引用它
3. 或在项目目录中创建 .env 文件，服务会自动加载该文件

API 参考

工具

• models(page=None, total=None) - 列出可用模型，可选择分页
• search(keywords) - 按关键字搜索模型
• schema(model_id) - 获取特定模型的 OpenAPI 架构
• generate(model, parameters, queue=False) - 使用模型生成内容
• result(url) - 获取排队请求的结果
• status(url) - 检查排队请求的状态
• cancel(url) - 取消排队请求
• upload(path - 将文件上传到 fal.ai CDN

---

附录：Docker 设置（实验性）

警告

此 Docker 设置为实验性，且不适用于 MCP 集成。

MCP 服务使用 stdio 传输，必须由 MCP 客户端启动。由于没有 stdin 连接，Docker 容器会立即退出。保留此设置仅供学习参考，也便于未来进行实验。

包含的 Docker 文件

• Dockerfile - 包含依赖项的 Python 3.10-slim 镜像
• docker-compose.yml - 带自动重启功能的 Compose 配置
• .dockerignore - 排除构建时不需要的文件

构建 Docker 镜像

docker-compose build

运行（将立即退出）

docker-compose up -d

容器将启动后立即退出，因为 MCP 服务需要活动的 stdin 连接。

为什么这样行不通

MCP 服务通过标准输入/输出（stdio）进行通信。它们旨在由 MCP 客户端作为子进程启动，而不是作为独立服务运行。在没有活动 stdin 连接的情况下于 Docker 中运行时，服务启动后会发现没有输入流，然后退出。

---

许可证

MIT