raveenb/fal-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:
Or install directly without adding the marketplace:
> **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:
**Claude Desktop Configuration for uvx:**
> **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**
**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
> **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 |
|----------|---------|-------------|