Skip to main content
Glama
Szotasz

fal-ai-mcp-server

by Szotasz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

Related MCP server: mcp-fal

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

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers