Skip to main content
Glama
Sign In
fal

fal

by derekalia
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

fal MCP Server

A Model Context Protocol (MCP) server for interacting with fal.ai models and services. This project was inspired by am0y's MCP server, but updated to use the latest streaming MCP support.

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

  • Full streaming support via HTTP transport

Related MCP server: mcp-fal

Requirements

  • Python 3.12+

  • fastmcp

  • httpx

  • aiofiles

  • A fal.ai API key

Installation

  1. Clone this repository:

git clone https://github.com/derekalia/fal.git
cd fal

  1. Install the required packages:

# Using uv (recommended)
uv sync

# Or using pip
pip install fastmcp httpx aiofiles

Usage

Running the Server Locally

  1. Get your fal.ai API key from fal.ai

  2. Start the MCP server with HTTP transport:

./run_http.sh YOUR_FAL_API_KEY

The server will start and display connection information in your terminal.

  1. Connect to it from your LLM IDE (Claude Code or Cursor) by adding to your configuration:

{
  "Fal": {
    "url": "http://127.0.0.1:6274/mcp/"
  }
}

Development Mode (with MCP Inspector)

For testing and debugging, you can run the server in development mode:

fastmcp dev main.py

This will:

  • Start the server on a random port

  • Launch the MCP Inspector web interface in your browser

  • Allow you to test all tools interactively with a web UI

The Inspector URL will be displayed in the terminal (typically http://localhost:PORT).

Environment Variables

The run_http.sh script automatically handles all environment variables for you. If you need to customize:

  • PORT: Server port for HTTP transport (default: 6274)

Setting API Key Permanently

If you prefer to set your API key permanently instead of passing it each time:

  1. Create a .env file in the project root:

echo 'FAL_KEY="YOUR_FAL_API_KEY_HERE"' > .env

  1. Then run the server without the API key argument:

./run_http.sh

For manual setup:

  • FAL_KEY: Your fal.ai API key (required)

  • MCP_TRANSPORT: Transport mode - stdio (default) or http

Available 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

License

MIT

Available Tools

8 tools
cancelB
    Cancel a queued request.
    
    Args:
        url: The cancel_url from a queued request
        
    Returns:
        The result of the cancellation attempt

Inputs: url (required).

generateC
    Generate content using a fal.ai model.
    
    Args:
        model: The model ID to use (e.g., "fal-ai/flux/dev")
        parameters: Model-specific parameters as a dictionary
        queue: Whether to use the queuing system (default: False)
        
    Returns:
        The model's response

Inputs: model (required), parameters (required), queue.

modelsA
    List available models on fal.ai. Ensure to use the total and page arguments. Avoid listing all the models at once.
    
    Args:
        page: The page number of models to retrieve (pagination)
        total: The total number of models to retrieve per page
        
    Returns:
        A list of models with their metadata

Inputs: page, total.

resultB
    Get the result of a queued request.
    
    Args:
        url: The response_url from a queued request
        
    Returns:
        The generation result

Inputs: url (required).

schemaB
    Get the OpenAPI schema for a specific model.
    
    Args:
        model_id: The ID of the model (e.g., "fal-ai/flux/dev")
        
    Returns:
        The OpenAPI schema for the model

Inputs: model_id (required).

searchC
    Search for models on fal.ai based on keywords.
    
    Args:
        keywords: The search terms to find models
        
    Returns:
        A list of models matching the search criteria

Inputs: keywords (required).

statusA
    Check the status of a queued request.
    
    Args:
        url: The status_url from a queued request
        
    Returns:
        The current status of the queued request

Inputs: url (required).

uploadC
    Upload a file to fal.ai storage.
    
    Args:
        path: The absolute path to the file to upload
        
    Returns:
        Information about the uploaded file, including the file_url

Inputs: path (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.5/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap between 'models' and 'search' as both retrieve model information, which could cause confusion. However, their specific functions (listing vs. keyword-based searching) are clarified in descriptions, preventing major misselection.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear, single-word verbs (e.g., cancel, generate, models, result). This uniformity makes the tool set predictable and easy to navigate, with no deviations in style.

    Tool Count5/5

    With 8 tools, the server is well-scoped for interacting with fal.ai's API, covering key operations like content generation, model management, and file handling. Each tool serves a specific function without unnecessary bloat.

    Completeness4/5

    The tool set covers core workflows for AI model interaction, including generation, queuing, model discovery, and file uploads. A minor gap exists in lacking tools for direct model management (e.g., updating or deleting models), but agents can work effectively with the provided operations.

    Resources

    Related MCP Connectors

    Related MCP Servers