🎨 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 (18 Tools)

Image Generation:

🖼️ generate_image - Create images from text prompts (Flux, SDXL, etc.)
🎯 generate_image_structured - Fine-grained control over composition, lighting, subjects
🔄 generate_image_from_image - Transform existing images with style transfer

Image Editing:

✂️ remove_background - Remove backgrounds from images (transparent PNG)
🔍 upscale_image - Upscale images 2x or 4x while preserving quality
✏️ edit_image - Edit images using natural language instructions
🎭 inpaint_image - Edit specific regions using masks
📐 resize_image - Smart resize for social media (Instagram, YouTube, TikTok, etc.)
🏷️ compose_images - Overlay images (watermarks, logos) with precise positioning

Video Tools:

🎬 generate_video - Text-to-video and image-to-video generation
📹 generate_video_from_image - Animate images into videos
🔀 generate_video_from_video - Video restyling and motion transfer

Audio Tools:

🎵 generate_music - Create instrumental music or songs with vocals

Utility Tools:

🔍 list_models - Discover 600+ available models with smart filtering
💡 recommend_model - AI-powered model recommendations for your task
💰 get_pricing - Check costs before generating content
📊 get_usage - View spending history and usage stats
⬆️ upload_file - Upload local files for use with generation tools

🔍 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 0: Claude Code Plugin (Simplest for Claude Code Users) 🔌

If you're using Claude Code, install directly via the plugin system:

bash

# Add the Luminary Lane Tools marketplace
/plugin marketplace add raveenb/fal-mcp-server

# Install the fal-ai plugin
/plugin install fal-ai@luminary-lane-tools

Or install directly without adding the marketplace:

bash

/plugin install fal-ai@raveenb/fal-mcp-server

Note: You'll need to set FAL_KEY in your environment before using the plugin.

Option 1: uvx (Recommended - Zero Install) ⚡

Run directly without installation using uv:

bash

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

# Or with specific version
uvx --from fal-mcp-server==1.4.0 fal-mcp

Claude Desktop Configuration for uvx:

config.json

{
  "mcpServers": {
    "fal-ai": {
      "command": "uvx",
      "args": ["--from", "fal-mcp-server", "fal-mcp"],
      "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.

Step 1: Start the Docker container

bash

# Pull and run with your API key
docker run -d \
  --name fal-mcp \
  -e FAL_KEY=your-api-key \
  -p 8080:8080 \
  ghcr.io/raveenb/fal-mcp-server:latest

# Verify it's running
docker logs fal-mcp

Step 2: Configure Claude Desktop to connect

Add to your Claude Desktop config file:

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

config.json

{
  "mcpServers": {
    "fal-ai": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8080/sse"]
    }
  }
}

Note: This uses mcp-remote to connect to the HTTP/SSE endpoint. Alternatively, if you have curl available: "command": "curl", "args": ["-N", "http://localhost:8080/sse"]

Step 3: Restart Claude Desktop

The fal-ai tools should now be available.

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

Using Docker Compose:

Terminal

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

⚠️ File Upload with Docker:

The upload_file tool requires volume mounts to access host files:

Terminal

docker run -d -p 8080:8080 \
  -e FAL_KEY="${FAL_KEY}" \
  -e FAL_MCP_TRANSPORT=http \
  -v ${HOME}/Downloads:/downloads:ro \
  -v ${HOME}/Pictures:/pictures:ro \
  ghcr.io/raveenb/fal-mcp-server:latest

Then use container paths like /downloads/image.png instead of host paths.

Feature	stdio (uvx)	Docker (HTTP/SSE)
`upload_file`	✅ Full filesystem	⚠️ Needs volume mounts
Security	Runs as user	Sandboxed container

Option 3: Install from PyPI

Terminal

pip install fal-mcp-server

Or with uv:

bash

uv pip install fal-mcp-server

Option 4: Install from source

bash

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

Configuration

Get your Fal.ai API key from fal.ai
Configure Claude Desktop by adding to:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

For PyPI/pip Installation:

config.json

{
  "mcpServers": {
    "fal-ai": {
      "command": "fal-mcp",
      "env": {
        "FAL_KEY": "your-fal-api-key"
      }
    }
  }
}

Note: For Docker configuration, see Option 2: Docker above.

For Source Installation:

config.json

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

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:

Code

# 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:

bash

# 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:

python

# 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

📚 Documentation

Guide	Description
Installation Guide	Detailed setup instructions for all platforms
API Reference	Complete tool documentation with parameters
Examples	Usage examples for image, video, and audio generation
Docker Guide	Container deployment and configuration
HTTP Transport	Web-based SSE transport setup
Local Testing	Running CI locally with `act`

📖 Full documentation site: raveenb.github.io/fal-mcp-server

🔌 Claude Code Plugin Marketplace

This project is part of the Luminary Lane Tools marketplace for Claude Code plugins.

Add the marketplace:

bash

/plugin marketplace add raveenb/fal-mcp-server

Available plugins:

Plugin	Description
`fal-ai`	Generate images, videos, and music using 600+ Fal.ai models

More plugins coming soon!

🔧 Troubleshooting

Common Errors

FAL_KEY not set

Code

Error: FAL_KEY environment variable is required

Solution: Set your Fal.ai API key:

server.ts

export FAL_KEY="your-api-key"

Model not found

Code

Error: Model 'xyz' not found

Solution: Use list_models to discover available models, or check the model ID spelling.

File not found (Docker)

Code

Error: File not found: /Users/username/image.png

Solution: When using Docker, mount the directory as a volume. See File Upload with Docker above.

Timeout on video/music generation

Code

Error: Generation timed out after 300s

Solution: Video and music generation can take several minutes. This is normal for high-quality models. Try:

Using a faster model variant (e.g., schnell instead of pro)
Reducing duration or resolution

Rate limiting

Code

Error: Rate limit exceeded

Solution: Wait a few minutes and retry. Consider upgrading your Fal.ai plan for higher limits.

Debug Mode

Enable verbose logging for troubleshooting:

server.ts

# Set debug environment variable
export FAL_MCP_DEBUG=true

# Run the server
fal-mcp

Reporting Issues

If you encounter a bug or unexpected behavior:

Check existing issues: GitHub Issues
Gather information:
- Error message (full text)
- Steps to reproduce
- Model ID used
- Environment (OS, Python version, transport mode)

Open a new issue with:

Code

**Error:** [paste error message]
**Steps to reproduce:** [what you did]
**Model:** [model ID if applicable]
**Environment:** [OS, Python version, Docker/uvx/pip]

Include logs if available (with sensitive data removed)

📝 Open an Issue

🤝 Contributing

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

Local Development

We support local CI testing with act:

bash

# 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

Hosted deployment

A hosted deployment is available on Fronteir AI.