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. - Native Async API - Uses falclient.runasync() for optimal performance - Queue Support - Long-running tasks (video/music) use queue API with progress updates - Non-blocking - All operations are truly asynchronous - STDIO - Traditional Model Con
Add this skill
npx mdskills install raveenb/fal-mcp-serverComprehensive MCP server for AI-powered media generation with excellent multi-transport support and 600+ models
1# 🎨 Fal.ai MCP Server23[](https://github.com/raveenb/fal-mcp-server/actions/workflows/ci.yml)4[](https://github.com/raveenb/fal-mcp-server/actions/workflows/docker.yml)5[](https://modelcontextprotocol.io)6[](https://github.com/raveenb/fal-mcp-server/releases)7[](https://pypi.org/project/fal-mcp-server/)8[](https://github.com/raveenb/fal-mcp-server/pkgs/container/fal-mcp-server)9[](https://www.python.org)10[](LICENSE)1112A Model Context Protocol (MCP) server that enables Claude Desktop (and other MCP clients) to generate images, videos, music, and audio using [Fal.ai](https://fal.ai) models.1314<a href="https://glama.ai/mcp/servers/@raveenb/fal-mcp-server">15 <img width="380" height="200" src="https://glama.ai/mcp/servers/@raveenb/fal-mcp-server/badge" alt="Fal.ai Server MCP server" />16</a>1718## ✨ Features1920### 🚀 Performance21- **Native Async API** - Uses fal_client.run_async() for optimal performance22- **Queue Support** - Long-running tasks (video/music) use queue API with progress updates23- **Non-blocking** - All operations are truly asynchronous2425### 🌐 Transport Modes (New!)26- **STDIO** - Traditional Model Context Protocol communication27- **HTTP/SSE** - Web-based access via Server-Sent Events28- **Dual Mode** - Run both transports simultaneously2930### 🎨 Media Generation (18 Tools)3132**Image Generation:**33- 🖼️ **generate_image** - Create images from text prompts (Flux, SDXL, etc.)34- 🎯 **generate_image_structured** - Fine-grained control over composition, lighting, subjects35- 🔄 **generate_image_from_image** - Transform existing images with style transfer3637**Image Editing:**38- ✂️ **remove_background** - Remove backgrounds from images (transparent PNG)39- 🔍 **upscale_image** - Upscale images 2x or 4x while preserving quality40- ✏️ **edit_image** - Edit images using natural language instructions41- 🎭 **inpaint_image** - Edit specific regions using masks42- 📐 **resize_image** - Smart resize for social media (Instagram, YouTube, TikTok, etc.)43- 🏷️ **compose_images** - Overlay images (watermarks, logos) with precise positioning4445**Video Tools:**46- 🎬 **generate_video** - Text-to-video and image-to-video generation47- 📹 **generate_video_from_image** - Animate images into videos48- 🔀 **generate_video_from_video** - Video restyling and motion transfer4950**Audio Tools:**51- 🎵 **generate_music** - Create instrumental music or songs with vocals5253**Utility Tools:**54- 🔍 **list_models** - Discover 600+ available models with smart filtering55- 💡 **recommend_model** - AI-powered model recommendations for your task56- 💰 **get_pricing** - Check costs before generating content57- 📊 **get_usage** - View spending history and usage stats58- ⬆️ **upload_file** - Upload local files for use with generation tools5960### 🔍 Dynamic Model Discovery (New!)61- **600+ Models** - Access all models available on Fal.ai platform62- **Auto-Discovery** - Models are fetched dynamically from the Fal.ai API63- **Smart Caching** - TTL-based cache for optimal performance64- **Flexible Input** - Use full model IDs or friendly aliases6566## 🚀 Quick Start6768### Prerequisites6970- Python 3.10 or higher71- [Fal.ai API key](https://fal.ai) (free tier available)72- Claude Desktop (or any MCP-compatible client)7374### Installation7576#### Option 0: Claude Code Plugin (Simplest for Claude Code Users) 🔌7778If you're using [Claude Code](https://claude.ai/code), install directly via the plugin system:7980```bash81# Add the Luminary Lane Tools marketplace82/plugin marketplace add raveenb/fal-mcp-server8384# Install the fal-ai plugin85/plugin install fal-ai@luminary-lane-tools86```8788Or install directly without adding the marketplace:89```bash90/plugin install fal-ai@raveenb/fal-mcp-server91```9293> **Note:** You'll need to set `FAL_KEY` in your environment before using the plugin.9495#### Option 1: uvx (Recommended - Zero Install) ⚡9697Run directly without installation using [uv](https://docs.astral.sh/uv/):9899```bash100# Run the MCP server directly101uvx --from fal-mcp-server fal-mcp102103# Or with specific version104uvx --from fal-mcp-server==1.4.0 fal-mcp105```106107**Claude Desktop Configuration for uvx:**108```json109{110 "mcpServers": {111 "fal-ai": {112 "command": "uvx",113 "args": ["--from", "fal-mcp-server", "fal-mcp"],114 "env": {115 "FAL_KEY": "your-fal-api-key"116 }117 }118 }119}120```121122> **Note:** Install uv first: `curl -LsSf https://astral.sh/uv/install.sh | sh`123124#### Option 2: Docker (Recommended for Production) 🐳125126Official Docker image available on GitHub Container Registry.127128**Step 1: Start the Docker container**129130```bash131# Pull and run with your API key132docker run -d \133 --name fal-mcp \134 -e FAL_KEY=your-api-key \135 -p 8080:8080 \136 ghcr.io/raveenb/fal-mcp-server:latest137138# Verify it's running139docker logs fal-mcp140```141142**Step 2: Configure Claude Desktop to connect**143144Add to your Claude Desktop config file:145- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`146- Windows: `%APPDATA%\Claude\claude_desktop_config.json`147148```json149{150 "mcpServers": {151 "fal-ai": {152 "command": "npx",153 "args": ["mcp-remote", "http://localhost:8080/sse"]154 }155 }156}157```158159> **Note:** This uses [mcp-remote](https://www.npmjs.com/package/mcp-remote) to connect to the HTTP/SSE endpoint. Alternatively, if you have `curl` available: `"command": "curl", "args": ["-N", "http://localhost:8080/sse"]`160161**Step 3: Restart Claude Desktop**162163The fal-ai tools should now be available.164165**Docker Environment Variables:**166167| Variable | Default | Description |168|----------|---------|-------------|169| `FAL_KEY` | (required) | Your Fal.ai API key |170| `FAL_MCP_TRANSPORT` | `http` | Transport mode: `http`, `stdio`, or `dual` |171| `FAL_MCP_HOST` | `0.0.0.0` | Host to bind the server to |172| `FAL_MCP_PORT` | `8080` | Port for the HTTP server |173174**Using Docker Compose:**175176```bash177curl -O https://raw.githubusercontent.com/raveenb/fal-mcp-server/main/docker-compose.yml178echo "FAL_KEY=your-api-key" > .env179docker-compose up -d180```181182**⚠️ File Upload with Docker:**183184The `upload_file` tool requires volume mounts to access host files:185186```bash187docker run -d -p 8080:8080 \188 -e FAL_KEY="${FAL_KEY}" \189 -e FAL_MCP_TRANSPORT=http \190 -v ${HOME}/Downloads:/downloads:ro \191 -v ${HOME}/Pictures:/pictures:ro \192 ghcr.io/raveenb/fal-mcp-server:latest193```194195Then use container paths like `/downloads/image.png` instead of host paths.196197| Feature | stdio (uvx) | Docker (HTTP/SSE) |198|---------|:-----------:|:-----------------:|199| `upload_file` | ✅ Full filesystem | ⚠️ Needs volume mounts |200| Security | Runs as user | Sandboxed container |201202#### Option 3: Install from PyPI203204```bash205pip install fal-mcp-server206```207208Or with uv:209```bash210uv pip install fal-mcp-server211```212213#### Option 4: Install from source214215```bash216git clone https://github.com/raveenb/fal-mcp-server.git217cd fal-mcp-server218pip install -e .219```220221### Configuration2222231. Get your Fal.ai API key from [fal.ai](https://fal.ai)2242252. Configure Claude Desktop by adding to:226 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`227 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`228229#### For PyPI/pip Installation:230```json231{232 "mcpServers": {233 "fal-ai": {234 "command": "fal-mcp",235 "env": {236 "FAL_KEY": "your-fal-api-key"237 }238 }239 }240}241```242243> **Note:** For Docker configuration, see [Option 2: Docker](#option-2-docker-recommended-for-production-) above.244245#### For Source Installation:246```json247{248 "mcpServers": {249 "fal-ai": {250 "command": "python",251 "args": ["/path/to/fal-mcp-server/src/fal_mcp_server/server.py"],252 "env": {253 "FAL_KEY": "your-fal-api-key"254 }255 }256 }257}258```2592603. Restart Claude Desktop261262## 💬 Usage263264### With Claude Desktop265266Once configured, ask Claude to:267268- "Generate an image of a sunset"269- "Create a video from this image"270- "Generate 30 seconds of ambient music"271- "Convert this text to speech"272- "Transcribe this audio file"273274### Discovering Available Models275276Use the `list_models` tool to discover available models:277278- "What image models are available?"279- "List video generation models"280- "Search for flux models"281282### Using Any Fal.ai Model283284You can use any model from the Fal.ai platform:285286```287# Using a friendly alias (backward compatible)288"Generate an image with flux_schnell"289290# Using a full model ID (new capability)291"Generate an image using fal-ai/flux-pro/v1.1-ultra"292"Create a video with fal-ai/kling-video/v1.5/pro"293```294295### HTTP/SSE Transport (New!)296297Run the server with HTTP transport for web-based access:298299```bash300# Using Docker (recommended)301docker run -d -e FAL_KEY=your-key -p 8080:8080 ghcr.io/raveenb/fal-mcp-server:latest302303# Using pip installation304fal-mcp-http --host 0.0.0.0 --port 8000305306# Or dual mode (STDIO + HTTP)307fal-mcp-dual --transport dual --port 8000308```309310Connect from web clients via Server-Sent Events:311- SSE endpoint: `http://localhost:8080/sse` (Docker) or `http://localhost:8000/sse` (pip)312- Message endpoint: `POST http://localhost:8080/messages/`313314See [Docker Documentation](docs/docker.md) and [HTTP Transport Documentation](docs/HTTP_TRANSPORT.md) for details.315316## 📦 Supported Models317318This 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.319320### Popular Aliases (Quick Reference)321322These friendly aliases are always available for commonly used models:323324| Alias | Model ID | Type |325|-------|----------|------|326| `flux_schnell` | `fal-ai/flux/schnell` | Image |327| `flux_dev` | `fal-ai/flux/dev` | Image |328| `flux_pro` | `fal-ai/flux-pro` | Image |329| `sdxl` | `fal-ai/fast-sdxl` | Image |330| `stable_diffusion` | `fal-ai/stable-diffusion-v3-medium` | Image |331| `svd` | `fal-ai/stable-video-diffusion` | Video |332| `animatediff` | `fal-ai/fast-animatediff` | Video |333| `kling` | `fal-ai/kling-video` | Video |334| `musicgen` | `fal-ai/musicgen-medium` | Audio |335| `musicgen_large` | `fal-ai/musicgen-large` | Audio |336| `bark` | `fal-ai/bark` | Audio |337| `whisper` | `fal-ai/whisper` | Audio |338339### Using Full Model IDs340341You can also use any model directly by its full ID:342343```python344# Examples of full model IDs345"fal-ai/flux-pro/v1.1-ultra" # Latest Flux Pro346"fal-ai/kling-video/v1.5/pro" # Kling Video Pro347"fal-ai/hunyuan-video" # Hunyuan Video348"fal-ai/minimax-video" # MiniMax Video349```350351Use `list_models` with category filters to discover more:352- `list_models(category="image")` - All image generation models353- `list_models(category="video")` - All video generation models354- `list_models(category="audio")` - All audio models355- `list_models(search="flux")` - Search for specific models356357## 📚 Documentation358359| Guide | Description |360|-------|-------------|361| [Installation Guide](docs/installation.md) | Detailed setup instructions for all platforms |362| [API Reference](docs/api.md) | Complete tool documentation with parameters |363| [Examples](docs/examples.md) | Usage examples for image, video, and audio generation |364| [Docker Guide](docs/docker.md) | Container deployment and configuration |365| [HTTP Transport](docs/HTTP_TRANSPORT.md) | Web-based SSE transport setup |366| [Local Testing](docs/LOCAL_TESTING.md) | Running CI locally with `act` |367368📖 **Full documentation site**: [raveenb.github.io/fal-mcp-server](https://raveenb.github.io/fal-mcp-server/)369370### 🔌 Claude Code Plugin Marketplace371372This project is part of the **Luminary Lane Tools** marketplace for Claude Code plugins.373374**Add the marketplace:**375```bash376/plugin marketplace add raveenb/fal-mcp-server377```378379**Available plugins:**380| Plugin | Description |381|--------|-------------|382| `fal-ai` | Generate images, videos, and music using 600+ Fal.ai models |383384*More plugins coming soon!*385386## 🔧 Troubleshooting387388### Common Errors389390#### FAL_KEY not set391```392Error: FAL_KEY environment variable is required393```394**Solution:** Set your Fal.ai API key:395```bash396export FAL_KEY="your-api-key"397```398399#### Model not found400```401Error: Model 'xyz' not found402```403**Solution:** Use `list_models` to discover available models, or check the model ID spelling.404405#### File not found (Docker)406```407Error: File not found: /Users/username/image.png408```409**Solution:** When using Docker, mount the directory as a volume. See [File Upload with Docker](#-file-upload-with-docker) above.410411#### Timeout on video/music generation412```413Error: Generation timed out after 300s414```415**Solution:** Video and music generation can take several minutes. This is normal for high-quality models. Try:416- Using a faster model variant (e.g., `schnell` instead of `pro`)417- Reducing duration or resolution418419#### Rate limiting420```421Error: Rate limit exceeded422```423**Solution:** Wait a few minutes and retry. Consider upgrading your Fal.ai plan for higher limits.424425### Debug Mode426427Enable verbose logging for troubleshooting:428429```bash430# Set debug environment variable431export FAL_MCP_DEBUG=true432433# Run the server434fal-mcp435```436437### Reporting Issues438439If you encounter a bug or unexpected behavior:4404411. **Check existing issues:** [GitHub Issues](https://github.com/raveenb/fal-mcp-server/issues)4424432. **Gather information:**444 - Error message (full text)445 - Steps to reproduce446 - Model ID used447 - Environment (OS, Python version, transport mode)4484493. **Open a new issue** with:450 ```451 **Error:** [paste error message]452 **Steps to reproduce:** [what you did]453 **Model:** [model ID if applicable]454 **Environment:** [OS, Python version, Docker/uvx/pip]455 ```4564574. **Include logs** if available (with sensitive data removed)458459[📝 Open an Issue](https://github.com/raveenb/fal-mcp-server/issues/new)460461## 🤝 Contributing462463Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.464465### Local Development466467We support local CI testing with `act`:468469```bash470# Quick setup471make ci-local # Run CI locally before pushing472473# See detailed guide474cat docs/LOCAL_TESTING.md475```476477## 📝 License478479MIT License - see [LICENSE](LICENSE) file for details.480481## 🙏 Acknowledgments482483- [Fal.ai](https://fal.ai) for providing the AI models484- [Anthropic](https://anthropic.com) for the MCP specification
Full transparency — inspect the skill content before installing.