am0y/mcp-fal

fal.ai MCP Server

A Model Context Protocol (MCP) server for interacting with fal.ai models and services.

Features

• List all available fal.ai models
• Search for specific models by keywords
• Get model schemas
• Generate content using any fal.ai model
• Support for both direct and queued model execution
• Queue management (status checking, getting results, cancelling requests)
• File upload to fal.ai CDN

Requirements

• Python 3.10+
• fastmcp
• httpx
• aiofiles
• A fal.ai API key

Installation

Manual Installation (Recommended)

1. Clone this repository:

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

2. Create a virtual environment and install dependencies:

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

3. Set your fal.ai API key as an environment variable:

export FAL_KEY="YOUR_FAL_API_KEY_HERE"

Docker Installation (Experimental)

1. Clone this repository:

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

2. Copy the environment template and add your API key:

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

3. Start the server:

docker-compose up -d

Usage

[!IMPORTANT] For MCP Integration (VS Code, Claude Desktop, Antigravity)

✅ Use Option 2 (Direct Python Execution) - This is the correct and recommended approach.

❌ Do NOT use Docker - MCP servers use stdio transport and must be spawned by MCP clients. Docker containers will exit immediately because there's no stdin connection.

[!NOTE] Why Docker doesn't work for MCP

MCP servers communicate via standard input/output (stdio). They're designed to be spawned as child processes by MCP clients, not run as standalone services. When you try to run an MCP server in Docker, it starts, finds no stdin connection, and exits immediately.

Option 1: Virtual Environment Setup (Recommended for MCP Integration)

Prerequisites: Python 3.10+ installed

Step 1: Create Virtual Environment

# Create virtual environment
python -m venv venv

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

Step 2: Install Dependencies

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

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

Step 3: Set Up API Key

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your fal.ai API key:

FAL_KEY=your_actual_fal_api_key_here

Option 2: Testing the Server Locally

For local testing and development (not required for MCP integration):

FastMCP Dev Mode

Launch the MCP Inspector web interface to test tools interactively:

fastmcp dev main.py

Direct Execution

Run the server directly (will wait for stdio input):

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

MCP Integration Configuration

After setting up the virtual environment above, configure your MCP client:

For Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/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"
            }
        }
    }
}

For VS Code/Antigravity (MCP settings):

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

For Linux/Mac, use:

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

Key Point: Use the venv Python interpreter (venv/Scripts/python.exe on Windows or venv/bin/python on Linux/Mac) so all dependencies are available.

Security Tip: Instead of hardcoding your API key, you can:

1. Set FAL_KEY as a system environment variable
2. Use "FAL_KEY": "${env:FAL_KEY}" in the config to reference it
3. Or create a .env file in the project directory and the server will load it automatically

API Reference

Tools

• models(page=None, total=None) - List available models with optional pagination
• search(keywords) - Search for models by keywords
• schema(model_id) - Get OpenAPI schema for a specific model
• generate(model, parameters, queue=False) - Generate content using a model
• result(url) - Get result from a queued request
• status(url) - Check status of a queued request
• cancel(url) - Cancel a queued request
• upload(path - Upload a file to fal.ai CDN

Appendix: Docker Setup (Experimental)

[!WARNING] This Docker setup is experimental and does NOT work for MCP integration.

MCP servers use stdio transport and must be spawned by MCP clients. Docker containers will exit immediately because there's no stdin connection. This is kept for educational purposes and potential future experimentation.

Docker Files Included

• Dockerfile - Python 3.10-slim image with dependencies
• docker-compose.yml - Compose configuration with auto-restart
• .dockerignore - Excludes unnecessary files from build

Building the Docker Image

docker-compose build

Running (Will Exit Immediately)

docker-compose up -d

The container will start and exit immediately because MCP servers require an active stdin connection.

Why This Doesn't Work

MCP servers communicate via standard input/output (stdio). They're designed to be spawned as child processes by MCP clients, not run as standalone services. When run in Docker without an active stdin connection, the server starts, finds no input stream, and exits.

License