fal-mcp-server 1.4.2

MCP server for Fal.ai - Generate images, videos, music and audio with AI models

🎨 Fal.ai MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop (and other MCP clients) to generate images, videos, music, and audio using Fal.ai models.

✨ Features

🚀 Performance

• Native Async API - Uses fal_client.run_async() for optimal performance
• Queue Support - Long-running tasks (video/music) use queue API with progress updates
• Non-blocking - All operations are truly asynchronous

🌐 Transport Modes (New!)

• STDIO - Traditional Model Context Protocol communication
• HTTP/SSE - Web-based access via Server-Sent Events
• Dual Mode - Run both transports simultaneously

🎨 Media Generation

• 🖼️ Image Generation - Create images using Flux, SDXL, and other models
• 🎬 Video Generation - Generate videos from images or text prompts
• 🎵 Music Generation - Create music from text descriptions
• 🗣️ Text-to-Speech - Convert text to natural speech
• 📝 Audio Transcription - Transcribe audio using Whisper
• ⬆️ Image Upscaling - Enhance image resolution
• 🔄 Image-to-Image - Transform existing images with prompts

🔍 Dynamic Model Discovery (New!)

• 600+ Models - Access all models available on Fal.ai platform
• Auto-Discovery - Models are fetched dynamically from the Fal.ai API
• Smart Caching - TTL-based cache for optimal performance
• Flexible Input - Use full model IDs or friendly aliases

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• Fal.ai API key (free tier available)
• Claude Desktop (or any MCP-compatible client)

Installation

Option 1: uvx (Recommended - Zero Install) ⚡

Run directly without installation using uv:

# Run the MCP server directly
uvx fal-mcp-server

# Or with specific version
uvx fal-mcp-server==1.2.0

Claude Desktop Configuration for uvx:

{
  "mcpServers": {
    "fal-ai": {
      "command": "uvx",
      "args": ["fal-mcp-server"],
      "env": {
        "FAL_KEY": "your-fal-api-key"
      }
    }
  }
}

Note: Install uv first: curl -LsSf https://astral.sh/uv/install.sh | sh

Option 2: Docker (Recommended for Production) 🐳

Official Docker image available on GitHub Container Registry:

# Pull the latest image
docker pull ghcr.io/raveenb/fal-mcp-server:latest

# Run with your API key (uses sensible defaults)
docker run -d \
  --name fal-mcp \
  -e FAL_KEY=your-api-key \
  -p 8080:8080 \
  ghcr.io/raveenb/fal-mcp-server:latest

Docker Environment Variables:

Variable	Default	Description
FAL_KEY	(required)	Your Fal.ai API key
FAL_MCP_TRANSPORT	http	Transport mode: http, stdio, or dual
FAL_MCP_HOST	0.0.0.0	Host to bind the server to
FAL_MCP_PORT	8080	Port for the HTTP server

# Example with custom configuration
docker run -d \
  --name fal-mcp \
  -e FAL_KEY=your-api-key \
  -e FAL_MCP_TRANSPORT=http \
  -e FAL_MCP_HOST=0.0.0.0 \
  -e FAL_MCP_PORT=8080 \
  -p 8080:8080 \
  ghcr.io/raveenb/fal-mcp-server:latest

Or use Docker Compose:

curl -O https://raw.githubusercontent.com/raveenb/fal-mcp-server/main/docker-compose.yml
echo "FAL_KEY=your-api-key" > .env
docker-compose up -d

Option 3: Install from PyPI

pip install fal-mcp-server

Or with uv:

uv pip install fal-mcp-server

Option 4: Install from source

git clone https://github.com/raveenb/fal-mcp-server.git
cd fal-mcp-server
pip install -e .

Configuration

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

2. Configure Claude Desktop by adding to:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

For Docker Installation:

{
  "mcpServers": {
    "fal-ai": {
      "command": "curl",
      "args": ["-N", "http://localhost:8080/sse"]
    }
  }
}

For PyPI Installation:

{
  "mcpServers": {
    "fal-ai": {
      "command": "python",
      "args": ["-m", "fal_mcp_server.server"],
      "env": {
        "FAL_KEY": "your-fal-api-key"
      }
    }
  }
}

For Source Installation:

{
  "mcpServers": {
    "fal-ai": {
      "command": "python",
      "args": ["/path/to/fal-mcp-server/src/fal_mcp_server/server.py"],
      "env": {
        "FAL_KEY": "your-fal-api-key"
      }
    }
  }
}

3. Restart Claude Desktop

💬 Usage

With Claude Desktop

Once configured, ask Claude to:

• "Generate an image of a sunset"
• "Create a video from this image"
• "Generate 30 seconds of ambient music"
• "Convert this text to speech"
• "Transcribe this audio file"

Discovering Available Models

Use the list_models tool to discover available models:

• "What image models are available?"
• "List video generation models"
• "Search for flux models"

Using Any Fal.ai Model

You can use any model from the Fal.ai platform:

# Using a friendly alias (backward compatible)
"Generate an image with flux_schnell"

# Using a full model ID (new capability)
"Generate an image using fal-ai/flux-pro/v1.1-ultra"
"Create a video with fal-ai/kling-video/v1.5/pro"

HTTP/SSE Transport (New!)

Run the server with HTTP transport for web-based access:

# Using Docker (recommended)
docker run -d -e FAL_KEY=your-key -p 8080:8080 ghcr.io/raveenb/fal-mcp-server:latest

# Using pip installation
fal-mcp-http --host 0.0.0.0 --port 8000

# Or dual mode (STDIO + HTTP)
fal-mcp-dual --transport dual --port 8000

Connect from web clients via Server-Sent Events:

• SSE endpoint: http://localhost:8080/sse (Docker) or http://localhost:8000/sse (pip)
• Message endpoint: POST http://localhost:8080/messages/

See Docker Documentation and HTTP Transport Documentation for details.

📦 Supported Models

This server supports 600+ models from the Fal.ai platform through dynamic discovery. Use the list_models tool to explore available models, or use any model ID directly.

Popular Aliases (Quick Reference)

These friendly aliases are always available for commonly used models:

Alias	Model ID	Type
flux_schnell	fal-ai/flux/schnell	Image
flux_dev	fal-ai/flux/dev	Image
flux_pro	fal-ai/flux-pro	Image
sdxl	fal-ai/fast-sdxl	Image
stable_diffusion	fal-ai/stable-diffusion-v3-medium	Image
svd	fal-ai/stable-video-diffusion	Video
animatediff	fal-ai/fast-animatediff	Video
kling	fal-ai/kling-video	Video
musicgen	fal-ai/musicgen-medium	Audio
musicgen_large	fal-ai/musicgen-large	Audio
bark	fal-ai/bark	Audio
whisper	fal-ai/whisper	Audio

Using Full Model IDs

You can also use any model directly by its full ID:

# Examples of full model IDs
"fal-ai/flux-pro/v1.1-ultra"      # Latest Flux Pro
"fal-ai/kling-video/v1.5/pro"     # Kling Video Pro
"fal-ai/hunyuan-video"            # Hunyuan Video
"fal-ai/minimax-video"            # MiniMax Video

Use list_models with category filters to discover more:

• list_models(category="image") - All image generation models
• list_models(category="video") - All video generation models
• list_models(category="audio") - All audio models
• list_models(search="flux") - Search for specific models

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Local Development

We support local CI testing with act:

# Quick setup
make ci-local  # Run CI locally before pushing

# See detailed guide
cat docs/LOCAL_TESTING.md

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Fal.ai for providing the AI models
• Anthropic for the MCP specification