Fal.ai

You can run the Fal.ai MCP Server to enable Claude Desktop and other MCP clients to generate images, videos, music, and audio using Fal.ai models. It supports multiple transport modes, dynamic model discovery, and both local (stdio) and web-based (HTTP/SSE) access, making it suitable for production or experimentation.

How to use

Connect your MCP client (such as Claude Desktop) to the Fal.ai MCP Server via one of two main transport modes. Use STDIO when you want a local, command-based connection and run the server on your machine. Use HTTP/SSE when you want web-based access, enabling clients to subscribe to server-sent events or post messages over HTTP. You can run both transports at the same time with dual mode.

- To use STDIO, start the server locally and configure your MCP client to invoke the standard command path. The example uses the uvx runtime to expose the MCP locally.
- To use HTTP/SSE, run the server in HTTP mode and point your MCP client at the SSE endpoint. The SSE endpoint is typically at /sse with message posting at /messages/.

When you’re connected, you can request content generation with high-level prompts such as generating images from text prompts, creating videos from images, or composing audio tracks. You can also discover models, get pricing or usage, and upload files for augmentation.

How to install

Prerequisites you need before you begin:

• Python 3.10 or higher

• A Fal.ai API key (free tier available)

• Claude Desktop or any MCP-compatible client

Choose one of the supported installation approaches below and follow the steps exactly as shown.

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:

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

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

{
  "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

# 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

{
  "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:

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:

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

pip install fal-mcp-server

Or with uv:

uv pip install fal-mcp-server

Option 4: Install from source

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

Additional configuration and notes

Configure your Fal.ai API key and choose your preferred transport. The server exposes both STDIO and HTTP/SSE interfaces, and you can run them in dual mode if you want to support both kinds of clients. Environment variables like FAL_KEY control authentication, while transport-related variables configure how the server binds and serves requests.

Environment variables you will commonly set:

• FAL_KEY: Your Fal.ai API key
• FAL_MCP_TRANSPORT: Transport mode (http,stdio,dual)
• FAL_MCP_HOST: Host to bind the server to
• FAL_MCP_PORT: Port for the HTTP server

{
  "mcpServers": {
    "falai_http": {
      "type": "http",
      "url": "http://localhost:8080/sse",
      "args": []
    },
    "falai_stdio": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "fal-mcp-server", "fal-mcp"],
      "env": {
        "FAL_KEY": "your-fal-api-key"
      }
    }
  },
  "envVars": [
    {"name": "FAL_KEY", "description": "Fal.ai API key", "required": true, "example": "your-api-key"},
    {"name": "FAL_MCP_TRANSPORT", "description": "Transport mode", "required": false, "example": "http"},
    {"name": "FAL_MCP_HOST", "description": "Host to bind the server to", "required": false, "example": "0.0.0.0"},
    {"name": "FAL_MCP_PORT", "description": "Port for the HTTP server", "required": false, "example": "8080"}
  ]
}

Troubleshooting and tips

Common issues you may see and how to address them include missing API keys, model not found errors, or timeouts during long generation tasks. Start by verifying your FAL_KEY, then use the list_models tool to confirm available models and IDs. If you run into timeouts for video or music tasks, consider shorter durations or faster model variants.

If you run into issues, enable verbose logging to gather more details and inspect the output for error messages related to authentication, transport, or model IDs.

Examples and tips

Discover models and use friendly aliases to simplify prompts. For example, you can request an image with a rapid alias like flux_schnell or a full model ID such as fal-ai/flux-pro/v1.1-ultra. You can also request a video or audio asset by referencing a full model ID dedicated to those tasks.

To connect a web client to the HTTP/SSE endpoint, use the SSE URL and POST endpoint for messages as shown in the transport configuration. You can run the HTTP server via Docker or pip, and you can also run a dual setup that supports both STDIO and HTTP transports.

Documentation and references

Explore supported model families, dynamic discovery, and the full set of tools available for image, video, and audio generation. Use the model list and aliases to quickly access popular capabilities.

Available tools

generate_image

Create images from text prompts using Fal.ai models with various model variants and fine-tuning options.

generate_image_structured

Generate images with fine-grained control over composition, lighting, and subjects for precise results.

generate_image_from_image

Transform an existing image using style transfer and other image-to-image capabilities.

remove_background

Remove backgrounds from images to create transparent PNGs.

upscale_image

Upscale images by 2x or 4x while preserving detail and quality.

edit_image

Edit images using natural language instructions to modify content or style.

inpaint_image

Edit specific regions using masks to perform targeted changes.

resize_image

Smartly resize images for social media dimensions.

compose_images

Overlay images, logos, or watermarks with precise positioning.

generate_video

Create video content from text prompts or image sequences.

generate_video_from_image

Animate a still image to generate a video sequence.

generate_video_from_video

Apply restyling and motion transfer to existing videos.

generate_music

Create instrumental music or songs with vocals via AI models.

list_models

Discover 600+ models available on Fal.ai with filters and friendly aliases.

recommend_model

AI-powered recommendations to match your task with model variants.

get_pricing

Check costs before generating content to manage budget.

get_usage

View spending history and usage statistics.

upload_file

Upload local files for use with generation tools.