🎨 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

Related MCP server: FL Studio MCP

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

Using Docker Compose:

⚠️ File Upload with Docker:

The upload_file tool requires volume mounts to access host files:

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

Option 3: Install from PyPI

Or with uv:

Option 4: Install from source

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 PyPI/pip Installation:

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

For Source Installation:

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:

HTTP/SSE Transport (New!)

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

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:

Using Full Model IDs

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

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

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

Available plugins:

More plugins coming soon!

🔧 Troubleshooting

Common Errors

FAL_KEY not set

Solution: Set your Fal.ai API key:

Model not found

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

File not found (Docker)

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

Timeout on video/music generation

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

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

Debug Mode

Enable verbose logging for troubleshooting:

Reporting Issues

If you encounter a bug or unexpected behavior:

1. Check existing issues: GitHub Issues

2. Gather information:

   • Error message (full text)

   • Steps to reproduce

   • Model ID used

   • Environment (OS, Python version, transport mode)

3. Open a new issue with:

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

4. 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:

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Fal.ai for providing the AI models

• Anthropic for the MCP specification