fal.ai MCP Server

fal.ai MCP サーバー

fal.ai のモデルおよびサービスと連携するための Model Context Protocol（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 クライアントによって子プロセスとして起動されるように設計されています。MCP サーバーを Docker で実行しようとすると、起動後、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 のウェブインターフェイスを起動して、ツールを対話的にテストします：

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"
            }
        }
    }
}

重要なポイント：すべての依存関係を利用できるように、venv の 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 サーバーは単独のサービスとして実行するのではなく、MCP クライアントによって子プロセスとして起動されるように設計されています。アクティブな stdin 接続なしで Docker 内で実行すると、サーバーは起動後、入力ストリームがないことを検知して終了します。

---

ライセンス

MIT