fal.ai MCP Server

An MCP (Model Context Protocol) server that gives Claude access to fal.ai generative AI models — images, videos, audio, 3D models, and more.

Built with FastMCP. Works with Claude Code and Claude Desktop.

Model Catalog

Image Generation (10 models)

Short Name	Model	Description	Price
flux-dev	FLUX.1 Dev	High-quality balanced generation	~$0.025/image
flux-schnell	FLUX.1 Schnell	Fast generation (4 steps)	~$0.003/image
flux-pro	FLUX.1 Pro v1.1	Best quality FLUX model	~$0.05/image
flux-kontext	FLUX Kontext Max	Context-aware editing, multi-image input	~$0.08/image
recraft-v4	Recraft V4	Typography and design-oriented	~$0.04/image
nano-banana	Nano Banana	Ultra-fast, ultra-cheap	~$0.001/image
nano-banana-2	Nano Banana 2	Gemini 3.1 Flash — text rendering, consistency	~$0.08/image
nano-banana-pro	Nano Banana Pro	Gemini 3 Pro — state-of-the-art	~$0.15/image
gpt-image	GPT-Image 1.5	OpenAI — high-fidelity, strong prompt adherence	~$0.13/image
gpt-image-2	GPT Image 2	OpenAI — latest model, fine typography, detailed images	token-based, ~$0.10–0.30
seedream-v4	Seedream V4	ByteDance — up to 4K resolution	~$0.03/image

Image Editing (4 models)

Short Name	Model	Description	Price
nano-banana-2-edit	Nano Banana 2 Edit	Gemini 3.1 Flash — fast editing, text rendering	~$0.08/edit
nano-banana-pro-edit	Nano Banana Pro Edit	Gemini 3 Pro — semantic editing, 14 ref images	~$0.15/edit
gpt-image-edit	GPT-Image 1.5 Edit	OpenAI — preserves composition and lighting	~$0.13/edit
gpt-image-2-edit	GPT Image 2 Edit	OpenAI — latest model, supports mask_url	token-based, ~$0.10–0.30
seedream-v4-edit	Seedream V4 Edit	ByteDance — context-aware editing	~$0.03/edit

Video Generation (5 models)

Short Name	Model	Description	Price
kling-v3-pro	Kling V3 Pro	High-quality text/image to video	~$0.30/video
sora-2-t2v	Sora 2 Text-to-Video	OpenAI Sora text-to-video	~$0.50/video
sora-2-i2v	Sora 2 Image-to-Video	OpenAI Sora image-to-video	~$0.50/video
ltx-2	LTX Video V2	Fast, affordable video	~$0.05/video
wan-v2	Wan 2.1	Alibaba's video model	~$0.10/video

Audio Generation (4 models)

Short Name	Model	Description	Price
chatterbox-tts	Chatterbox TTS	High-quality text-to-speech	~$0.01/gen
minimax-speech	MiniMax Speech 02 HD	HD multi-voice synthesis	~$0.02/gen
beatoven-music	Beatoven Music	AI music from text	~$0.05/gen
beatoven-sfx	Beatoven SFX	Sound effects	~$0.03/gen

3D Generation (2 models)

Short Name	Model	Description	Price
meshy-v6	Meshy V6	Image to 3D model	~$0.15/model
trellis-2	Trellis 2	Fast image to 3D with textures	~$0.10/model

Utility (2 models)

Short Name	Model	Description	Price
remove-bg	Background Removal	Remove image background	~$0.005/image
upscale	Aura SR Upscale	4x image upscaling	~$0.01/image

Available Tools

Synchronous (block until result, best for fast models)

Tool	Description
generate_image	Generate images from text prompts
edit_image	Edit/transform existing images
generate_video	Generate video from text and/or image
generate_audio	Text-to-speech, music, and sound effects
generate_3d	Generate 3D models from images
remove_background	Remove image backgrounds
upscale_image	Upscale images to higher resolution
run_model	Run any fal.ai model with custom arguments
list_models	List all available models from the catalog

Asynchronous queue API (for long-running jobs — video, 3D, large batches)

The synchronous tools block while the model runs. For models that take longer than the MCP tool-call timeout (~60 s), use the queue API instead: submit returns immediately with a request_id, then poll and fetch separately.

Tool	Description
submit_job(model, arguments, media_type, prefix, webhook_url?)	Submit a job, return request_id immediately
poll_job(request_id, with_logs?)	Check status: IN_QUEUE (with queue_position), IN_PROGRESS (with logs), or COMPLETED
fetch_job(request_id)	Once COMPLETED, fetch result and download files locally
cancel_job(request_id)	Cancel a queued or in-progress job
list_jobs(status_filter?, limit?)	List locally tracked jobs (most recent first)

Utilities

Tool	Description
read_file_base64(path)	Read a local file and return {mime_type, size, data_url, base64}. Useful for inlining downloaded images into artifact UIs that can't load file:// due to CSP.

Job metadata (request_id → model_id, media_type, prefix, status, files) is persisted in jobs.json next to server.py, so poll_job and fetch_job only need the request_id.

Example flow:

submit_job(model="kling-v3-pro", arguments={"prompt":"a fox jumping","duration":"5"}, media_type="video", prefix="fox")
  → {"request_id": "019dd...", "status": "SUBMITTED"}
poll_job("019dd...")           → {"status": "IN_PROGRESS", ...}
poll_job("019dd...")           → {"status": "COMPLETED"}
fetch_job("019dd...")          → {"files": [{"local_path": "~/Downloads/fal-ai/videos/fox_..."}]}

Installation

Prerequisites

• Python 3.10+
• A fal.ai account with an API key

1. Get your fal.ai API key

Go to fal.ai Dashboard > Keys and create an API key.

2. Set up the server

git clone https://github.com/Szotasz/fal-ai-mcp-server.git
cd fal-ai-mcp-server
python -m venv .venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Set your API key

export FAL_KEY="your-api-key-here"

Usage with Claude Code

claude mcp add fal-ai \
  -e FAL_KEY=your-api-key-here \
  -- /path/to/fal-ai-mcp-server/.venv/bin/python /path/to/fal-ai-mcp-server/server.py

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "fal-ai": {
      "command": "/path/to/fal-ai-mcp-server/.venv/bin/python",
      "args": ["/path/to/fal-ai-mcp-server/server.py"],
      "env": {
        "FAL_KEY": "your-api-key-here"
      }
    }
  }
}

Replace /path/to/fal-ai-mcp-server with the actual path where you cloned the repo.

Output

Generated files are automatically downloaded to ~/Downloads/fal-ai/ organized by type:

• images/ — generated and edited images
• videos/ — generated videos
• audio/ — speech, music, and sound effects
• 3d/ — 3D models
• other/ — everything else

License

MIT