Skip to main content
Glama
MohsenMousaviEyeline

mcp-fal

by MohsenMousaviEyeline
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Remote

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

Related MCP server: @monsoft/mcp-fal-ai

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

Available Tools

3 tools
generate_imageA

Generate one or more images from a text prompt using Fal.ai image generation models. Supports models like FLUX (fal-ai/flux/dev, fal-ai/flux/schnell), Stable Diffusion, and more. Returns the URL(s) of the generated image(s).

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesThe text prompt describing the image to generate.
model_idNoThe Fal.ai model ID to use for generation. Defaults to 'fal-ai/flux/dev'. Examples: 'fal-ai/flux/dev', 'fal-ai/flux/schnell', 'fal-ai/stable-diffusion-v3-medium'.fal-ai/flux/dev
image_sizeNoThe size/aspect ratio of the output image. Options: 'square_hd', 'square', 'portrait_4_3', 'portrait_16_9', 'landscape_4_3', 'landscape_16_9'. Defaults to 'landscape_4_3'.
num_imagesNoNumber of images to generate (1–4). Defaults to 1.
negative_promptNoText describing what to exclude from the image (not supported by all models).
seedNoRandom seed for reproducible results. Omit for a random seed.

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavior. It covers generating one or more images, supported models, and return of URLs. It could mention default model and size, but overall transparency is good. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose, no extraneous words. Concise and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters with full schema coverage, no output schema, but the description explains return type (URLs). All necessary information for an image generation tool is covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds context by mentioning specific models (FLUX, Stable Diffusion) which relates to the model_id parameter, but does not add significant semantic value beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates images from a text prompt using Fal.ai models. It specifies the return of URLs and distinguishes from siblings like generate_video. The verb 'generate' and resource 'image' are specific and appropriate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for text-to-image generation but does not explicitly state when to use this tool over siblings like generate_video or run_model. No exclusion criteria or alternative suggestions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_videoA

Generate a video from a text prompt (text-to-video) or from an input image (image-to-video) using Fal.ai video generation models. Supports models like MiniMax (Hailuo AI), HunyuanVideo, Mochi 1, and more. Returns the URL of the generated video. Note: video generation can take 1–5 minutes.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYesThe text prompt describing the video to generate.
model_idNoThe Fal.ai model ID to use for generation. Defaults to 'fal-ai/minimax-video/image-to-video' for image-to-video, or 'fal-ai/minimax-video/text-to-video' for text-to-video. Other options: 'fal-ai/hunyuan-video', 'fal-ai/mochi-v1'.
image_urlNoURL of an input image to animate (for image-to-video models). When provided, defaults to using 'fal-ai/minimax-video/image-to-video'.
durationNoDesired video duration in seconds (model-dependent, not all models support this).

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses generation time (1-5 minutes) and that it returns a URL. However, no details on error handling, rate limits, or cost. Since annotations are absent, the description partially fills the gap but could be richer.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise with three sentences, no redundancy. Each sentence serves a purpose: defining capability, listing models, and noting runtime.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers basic usage and output (URL) but lacks details on asynchronous behavior (e.g., polling vs. blocking), error states, or limitations beyond time. Adequate but not fully comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds context beyond schema descriptions, such as default model selection based on image_url presence and examples of supported models. The duration parameter is noted as model-dependent, providing valuable usage insight.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool generates videos from text or image input using specific models. It distinguishes itself from siblings by focusing on video generation vs. image generation or general model running.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage based on input type (text vs. image) but no explicit guidance on when to use this tool over generate_image or run_model. Missing when-not-to-use or alternative recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_modelA

Run any Fal.ai model by its model ID with arbitrary input parameters. This is a flexible, low-level tool that gives you access to all 1000+ models on Fal.ai without needing a dedicated tool for each one. Consult the Fal.ai model catalog at https://fal.ai/models for available models and their parameters.

ParametersJSON Schema
NameRequiredDescriptionDefault
model_idYesThe Fal.ai model ID to run. Examples: 'fal-ai/flux/dev', 'fal-ai/stable-audio', 'fal-ai/face-swap', 'fal-ai/imageutils/rembg'.
inputYesThe model-specific input parameters as a JSON object. Refer to the model's documentation for available parameters.

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully convey behavioral traits. It mentions 'low-level' but omits details on authentication, rate limits, error handling, output format, or side effects of running arbitrary models.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, and every sentence is essential. No extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a generic model runner with no output schema, the description adequately explains the purpose and where to find model details. It could be improved by noting that outputs vary per model or that results are returned directly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with clear descriptions for model_id and input. The description adds no new meaning beyond what the schema already provides, resulting in a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Run any Fal.ai model by its model ID with arbitrary input parameters', specifying the verb (run), resource (Fal.ai model), and scope (any model). It distinguishes from siblings generate_image and generate_video by being a general-purpose tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains this is a flexible, low-level tool for all models and directs users to the model catalog for parameters. However, it does not explicitly advise when to prefer sibling tools or mention exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedgenerate_image
    • First observedgenerate_video
    • First observedrun_model
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a clearly distinct domain: image generation, video generation, and a catch-all for any other model. There is no ambiguity or overlap between them.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (generate_image, generate_video, run_model), making them predictable and easy to understand.

Tool Count5/5

Three tools is an ideal number for this server: two specialized tools for the most common tasks and one flexible tool that covers the remaining 1000+ models. The scope is well-scoped without being overwhelming.

Completeness4/5

The specialized tools handle the primary use cases (image and video generation), and run_model fills any gaps. However, dedicated tools for other popular model categories (e.g., audio) could improve discoverability, though run_model covers them.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers