mcp-fal

An MCP (Model Context Protocol) server that exposes Fal.ai generative media models as tools callable by Claude and other MCP-compatible clients.

Features

Tool	Description
generate_image	Generate images from a text prompt using FLUX, Stable Diffusion, and other models
generate_video	Generate videos via text-to-video or image-to-video using MiniMax, HunyuanVideo, and more
run_model	Run any Fal.ai model by ID with arbitrary input — access to 1000+ models

---

Installation

# Clone the repository
git clone https://github.com/mohsenmousavieyeline/mcp-fal.git
cd mcp-fal

# Install dependencies
npm install

# Build (compiles TypeScript → dist/)
npm run build

---

API Key

Get your Fal.ai API key at https://fal.ai/dashboard/keys.

The server resolves the API key in this priority order:

1. CLI argument — --api-key <your-key>
2. Environment variable — FAL_KEY=<your-key>

---

Configuration

Claude Desktop

Add the server to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Option A — API key as CLI argument (recommended):

{
  "mcpServers": {
    "fal-ai": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-fal/dist/index.js",
        "--api-key",
        "fal_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ]
    }
  }
}

Option B — API key as environment variable:

{
  "mcpServers": {
    "fal-ai": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-fal/dist/index.js"],
      "env": {
        "FAL_KEY": "fal_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add fal-ai -- node /absolute/path/to/mcp-fal/dist/index.js --api-key fal_xxxx

Or with an environment variable:

FAL_KEY=fal_xxxx claude mcp add fal-ai -- node /absolute/path/to/mcp-fal/dist/index.js

npx (no installation)

If published to npm:

{
  "mcpServers": {
    "fal-ai": {
      "command": "npx",
      "args": ["mcp-fal", "--api-key", "fal_xxxx"]
    }
  }
}

---

Tool Reference

generate_image

Generate one or more images from a text prompt.

Parameter	Type	Required	Default	Description
prompt	string	✅	—	Text description of the image
model_id	string	—	fal-ai/flux/dev	Fal.ai model ID
image_size	string	—	landscape_4_3	square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9
num_images	integer	—	1	Number of images (1–4)
negative_prompt	string	—	—	What to exclude from the image
seed	integer	—	—	Seed for reproducible results

Example prompt to Claude:

"Generate an image of a misty mountain landscape at dawn using FLUX schnell"

---

generate_video

Generate a video from text or an input image.

Parameter	Type	Required	Default	Description
prompt	string	✅	—	Text description of the video
model_id	string	—	Auto-selected	Fal.ai model ID
image_url	string	—	—	Input image URL (triggers image-to-video)
duration	number	—	—	Desired duration in seconds

Default models:

• With image_url: fal-ai/minimax-video/image-to-video
• Without image_url: fal-ai/minimax-video/text-to-video

⚠️ Video generation typically takes 1–5 minutes.

Example prompt to Claude:

"Generate a 5-second video of ocean waves crashing on a rocky shore"

---

run_model

Run any Fal.ai model with custom parameters.

Parameter	Type	Required	Description
model_id	string	✅	Fal.ai model ID (e.g. fal-ai/imageutils/rembg)
input	object	✅	Model-specific input parameters

Browse available models at https://fal.ai/models.

Example prompt to Claude:

"Use the run_model tool with fal-ai/imageutils/rembg to remove the background from this image: https://example.com/photo.jpg"

---

Development

# Run in development mode (no build step required)
FAL_KEY=your_key npm run dev

# Build for production
npm run build

# Run the built server
FAL_KEY=your_key npm start

---

Popular Fal.ai Models

Category	Model ID	Description
Image	fal-ai/flux/dev	FLUX.1 Dev — high quality
Image	fal-ai/flux/schnell	FLUX.1 Schnell — fast
Image	fal-ai/stable-diffusion-v3-medium	Stable Diffusion 3
Video	fal-ai/minimax-video/text-to-video	MiniMax text-to-video
Video	fal-ai/minimax-video/image-to-video	MiniMax image-to-video
Video	fal-ai/hunyuan-video	HunyuanVideo
Video	fal-ai/mochi-v1	Mochi 1
Utility	fal-ai/imageutils/rembg	Background removal

---

License

MIT