fal-ai

Fal AI MCP Server exposes the fal.ai APIs to generate images and videos through the MCP protocol. Once added to your MCP configuration, you can invoke its tools by sending model-context calls through the MCP client, allowing you to generate media assets using fal.ai models and endpoints. The server reads the FAL_KEY for authentication and saves generated media to the path specified by SAVE_MEDIA_DIR. You can run the server via uvx (preferred) or uv, then point your MCP config to the server entry. The server is designed to be a barebones foundation that can be extended to support additional fal.ai models and endpoints as needed.

To start using it, configure the MCP entry with uvx and the appropriate environment variables, or run uv in a directory containing the server and point to main.py if you prefer the local Python execution path. The key capabilities are image generation and video generation through fal.ai APIs, with media outputs saved to your designated directory for downstream processing.

Prerequisites:

• Python 3.8+ (recommended)
• git
• uv (optional, for local development) or uvx (preferred for MCP integration)
• Access to fal.ai API and a valid FAL_KEY key

Installation steps:

1. Clone the repository: git clone https://github.com/piebro/piebro-fal-ai-mcp-server.git cd piebro-fal-ai-mcp-server

2. Create and activate a Python virtual environment (optional but recommended): python3 -m venv venv source venv/bin/activate # on Unix or macOS venv\Scripts\activate # on Windows

3. Install Python dependencies (if a requirements file exists): pip install -r requirements.txt # or install specific packages as needed

4. Install uv or uvx for MCP usage:

   • For uvx (preferred): follow the uv documentation to install and verify uvx is available in your PATH
   • For uv (local development): ensure uv is installed and accessible

5. Verify environment setup:

   • Ensure FAL_KEY and SAVE_MEDIA_DIR are set in your environment or provided in the MCP config when running the server

6. Run a test start (example using uvx as in the README): uvx fal-ai-mcp-server

7. Optional: run the server directly with Python (if you prefer): uv run ./main.py # depending on your directory structure

Note: The exact commands may vary slightly depending on how you structure the repository locally. The README provides two main entry points: using uvx with a packaged entry (fal-ai-mcp-server) or using uv with a local main.py entry.

Environment variables:

• FAL_KEY: Your fal.ai API key. Keep this secret.
• SAVE_MEDIA_DIR: Directory path where generated media will be saved. Ensure the directory exists and is writable.

Common issues:

• If the API key is invalid or missing, requests to fal.ai will fail. Double-check FAL_KEY in your environment and MCP config.
• If SAVE_MEDIA_DIR is not writable, media generation may fail; verify directory permissions.
• When using uv, ensure the working directory contains the expected entry point (e.g., main.py) if you opt for the local run method.

Advanced usage:

• You can extend the server to support additional fal.ai models or endpoints by modifying the server code to add new routes, handlers, or model mappings.
• Consider setting timeouts and rate limits in your MCP client configuration to align with fal.ai API usage policies.