fal-ai-mcp-server

v2.1.4

Published

a month ago

Model Context Protocol (MCP) server for fal.ai - interact with AI models through Claude and other MCP clients. Now with Platform API v1 support!

0High
0Medium
0Low

d_posty

mcp model-context-protocol fal fal.ai ai image-generation llm claude

fal.ai MCP Server

A Model Context Protocol (MCP) server for interacting with fal.ai models and services. This server enables Claude Desktop and other MCP clients to discover, search, and generate content using fal.ai's powerful AI models.

Features

Model Discovery: List and search through fal.ai's model gallery using Platform API v1
Advanced Search: Free-text search with filtering by category, status, and more
Model Lookup: Find specific models by endpoint ID with optional schema expansion
Pricing Information: Get real-time pricing for models (output-based or GPU-based)
Cost Estimation: Estimate costs using historical API pricing or unit pricing
Usage Tracking: Get detailed billing usage records with time-series data
Analytics: Track request counts, latency statistics, and success/error rates
Schema Inspection: Get detailed input/output schemas with inline OpenAPI expansion
Content Generation: Generate images, videos, and other content using AI models
Queue Management: Track generation status, retrieve results, and cancel requests
File Upload: Upload files to fal.ai CDN for use with models
Full TypeScript Support: Type-safe API with comprehensive TypeScript definitions
Cursor-based Pagination: Efficient pagination through large result sets

Installation

Via npm (Recommended)

npm install -g fal-ai-mcp-server

From Source

git clone https://github.com/derekalia/fal-mcp-ts
cd fal-mcp-ts
npm install
npm run build
npm link

Configuration

Get Your API Key

Sign up at fal.ai
Navigate to your API keys page
Create a new API key

Configure MCP Client

Add the server to your MCP client configuration. The API key should be provided via environment variables.

Claude Desktop

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": {
      "command": "npx",
      "args": ["-y", "fal-ai-mcp-server"],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      }
    }
  }
}

Claude Code

For project-specific configuration, create a .mcp.json file in your project root:

{
  "mcpServers": {
    "fal": {
      "command": "npx",
      "args": ["-y", "fal-ai-mcp-server@latest"],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      }
    }
  }
}

Using @latest ensures you always get the newest version automatically!

Security Note: Never commit .mcp.json files containing API keys to version control. Add it to your .gitignore file.

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "fal": {
      "command": "npx",
      "args": ["-y", "fal-ai-mcp-server"],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      }
    }
  }
}

Other MCP Clients

For other MCP clients, use the command:

FAL_KEY="your-api-key" npx -y fal-ai-mcp-server

Available Tools

`models`

List available models in the fal.ai model gallery using the Platform API v1.

Parameters:

category (optional): Filter by category (e.g., "text-to-image", "image-to-video", "training")
cursor (optional): Pagination cursor from previous response
limit (optional): Models per page (default: 100, max: 100)
status (optional): Filter by status - "active" or "deprecated"
expand (optional): Array of fields to expand. Supported: ["openapi-3.0"] to include full OpenAPI schema

Example:

{
  "category": "text-to-image",
  "status": "active",
  "limit": 50,
  "expand": ["openapi-3.0"]
}

`search`

Search for models using free-text query across name, description, and category.

Parameters:

query (required): Free-text search query
cursor (optional): Pagination cursor from previous response
limit (optional): Results per page (default: 50, max: 100)
category (optional): Filter by category
status (optional): Filter by status - "active" or "deprecated"
expand (optional): Array of fields to expand. Supported: ["openapi-3.0"]

Example:

{
  "query": "flux image generation",
  "status": "active",
  "limit": 20
}

`find`

Find specific model(s) by endpoint ID. Can retrieve single or multiple models.

Parameters:

endpoint_ids (required): Array of endpoint IDs (1-50 models)
expand (optional): Array of fields to expand. Supported: ["openapi-3.0"]

Example:

{
  "endpoint_ids": ["fal-ai/flux/dev", "fal-ai/flux-pro"],
  "expand": ["openapi-3.0"]
}

`schema`

Get the input/output schema for a specific model.

Parameters:

app_id (required): Model application ID (e.g., "fal-ai/flux/dev")

Example:

{
  "app_id": "fal-ai/flux/dev"
}

`generate`

Submit a generation request to a fal.ai model.

Parameters:

app_id (required): Model application ID
input_data (required): Model-specific input parameters
webhook_url (optional): Webhook for result notification
output_format (optional): "json" or "binary" (default: "json")

Example:

{
  "app_id": "fal-ai/flux/dev",
  "input_data": {
    "prompt": "A beautiful sunset over mountains",
    "image_size": "landscape_4_3",
    "num_inference_steps": 28
  }
}

`result`

Get the result of a generation request.

Parameters:

app_id (required): Model application ID
request_id (required): Request ID from generate()

Example:

{
  "app_id": "fal-ai/flux/dev",
  "request_id": "abc123-def456-ghi789"
}

`status`

Check the status of a generation request without fetching full results.

Parameters:

app_id (required): Model application ID
request_id (required): Request ID to check

Example:

{
  "app_id": "fal-ai/flux/dev",
  "request_id": "abc123-def456-ghi789"
}

`cancel`

Cancel a pending or processing generation request.

Parameters:

app_id (required): Model application ID
request_id (required): Request ID to cancel

Example:

{
  "app_id": "fal-ai/flux/dev",
  "request_id": "abc123-def456-ghi789"
}

`upload`

Upload a file to fal.ai CDN for use with models.

Parameters:

file_path (required): Path to the file to upload
content_type (optional): MIME type (auto-detected if not provided)

Example:

{
  "file_path": "/path/to/image.png"
}

`pricing`

Get pricing information for specific model endpoint(s). Requires authentication.

Parameters:

endpoint_ids (required): Array of endpoint IDs to get pricing for (1-50 models)
cursor (optional): Pagination cursor from previous response

Example:

{
  "endpoint_ids": ["fal-ai/flux/dev", "fal-ai/flux-pro"]
}

Response:

{
  "prices": [
    {
      "endpoint_id": "fal-ai/flux/dev",
      "unit_price": 0.025,
      "unit": "image",
      "currency": "USD"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

`estimate_cost`

Estimate costs for model operations. Requires authentication. Useful for budget planning and cost optimization.

Estimation Methods:

Historical API Price (historical_api_price):
- Based on historical pricing per API call from past usage patterns
- Use when you know the number of API calls you'll make
- Example: "How much will 100 calls to flux/dev cost?"
Unit Price (unit_price):
- Based on unit price × expected billing units (images, videos, etc.)
- Use when you know the expected output quantity
- Example: "How much will 50 images from flux/dev cost?"

Parameters:

estimate_type (required): Either "historical_api_price" or "unit_price"
endpoints (required): Map of endpoint IDs to quantities

Example - Historical API Price:

{
  "estimate_type": "historical_api_price",
  "endpoints": {
    "fal-ai/flux/dev": {
      "call_quantity": 100
    },
    "fal-ai/flux/schnell": {
      "call_quantity": 50
    }
  }
}

Example - Unit Price:

{
  "estimate_type": "unit_price",
  "endpoints": {
    "fal-ai/flux/dev": {
      "unit_quantity": 50
    },
    "fal-ai/flux-pro": {
      "unit_quantity": 25
    }
  }
}

Response:

{
  "estimate_type": "unit_price",
  "total_cost": 1.88,
  "currency": "USD"
}

`usage`

Get usage records for your workspace with detailed billing information. Returns time-series data and/or summary statistics with unit quantities and prices. Requires authentication.

Parameters:

endpoint_ids (required): Array of endpoint IDs to get usage for (1-50 models)
start (optional): Start date in ISO8601 format (e.g., "2025-01-01" or "2025-01-01T00:00:00Z"). Defaults to 24 hours ago
end (optional): End date in ISO8601 format. Defaults to current time
timeframe (optional): Aggregation timeframe - "minute", "hour", "day", "week", or "month". Auto-detected if not specified
timezone (optional): Timezone for date aggregation (e.g., "UTC", "America/New_York"). Defaults to "UTC"
bound_to_timeframe (optional): Whether to align start/end dates to timeframe boundaries. Defaults to true
expand (optional): Array of data to include - "time_series", "summary", "auth_method". Defaults to ["time_series"]
cursor (optional): Pagination cursor from previous response
limit (optional): Maximum number of items to return

Example:

{
  "endpoint_ids": ["fal-ai/flux/dev", "fal-ai/nano-banana"],
  "start": "2025-10-01",
  "end": "2025-10-31",
  "timeframe": "day",
  "expand": ["time_series", "summary"]
}

Response:

{
  "time_series": [
    {
      "bucket": "2025-10-23T00:00:00+00:00",
      "results": [
        {
          "endpoint_id": "fal-ai/flux/dev",
          "unit": "shared_gateway_request",
          "quantity": 8,
          "unit_price": 0.025
        }
      ]
    }
  ],
  "summary": [
    {
      "endpoint_id": "fal-ai/flux/dev",
      "unit": "shared_gateway_request",
      "quantity": 15,
      "unit_price": 0.025
    }
  ]
}

`analytics`

Get analytics data for model endpoints with time-bucketed metrics. Returns request counts, latency statistics (avg, p50, p95, p99), and success/error rates. Requires authentication.

Parameters:

endpoint_ids (required): Array of endpoint IDs to get analytics for (1-50 models)
start (optional): Start date in ISO8601 format. Defaults to 24 hours ago
end (optional): End date in ISO8601 format. Defaults to current time
timeframe (optional): Time bucket size - "hour", "day", "week", or "month". Auto-detected if not specified
timezone (optional): Timezone for date aggregation. Defaults to "UTC"
bound_to_timeframe (optional): Whether to align start/end dates to timeframe boundaries. Defaults to true
metric (optional): Filter to return only specific metric - "total_requests", "successful_requests", "failed_requests", or "avg_latency_ms"
cursor (optional): Pagination cursor from previous response
limit (optional): Maximum number of items to return

Example:

{
  "endpoint_ids": ["fal-ai/flux/dev"],
  "start": "2025-10-01",
  "timeframe": "day"
}

Response:

{
  "time_series": [
    {
      "bucket": "2025-10-23T00:00:00+00:00",
      "results": [
        {
          "endpoint_id": "fal-ai/flux/dev",
          "request_count": 19
        }
      ]
    }
  ]
}

Usage Examples

With Claude Desktop

Once configured, you can use natural language to interact with fal.ai:

Model Discovery:

"Search for active flux models"

"Find the model details for fal-ai/flux/dev"

Pricing & Cost Management:

"Get pricing information for fal-ai/flux/dev and fal-ai/flux-pro"

"Estimate the cost of generating 50 images using fal-ai/flux/dev"

"How much would 100 API calls to flux/dev cost based on historical pricing?"

Usage & Analytics:

"Show me my usage for fal-ai/nano-banana in the last 2 weeks"

"Get analytics for fal-ai/flux/dev for the past month"

"What's my total spending on flux/dev this month?"

Content Generation:

"Generate an image of a cat wearing a hat using fal-ai/flux/dev"

"Check the status of my last generation request"

"Upload this image to fal.ai CDN: /path/to/image.png"

Programmatic Usage

You can also use the server programmatically:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
// ... server setup

Development

Prerequisites

Node.js 18 or later
npm or yarn
fal.ai API key

Setup

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

# Install dependencies
npm install

# Build
npm run build

# Run in development mode with watch
npm run watch

Project Structure

fal-mcp-ts/
├── src/
│   ├── index.ts           # Main server entry point
│   ├── client.ts          # Fal.ai client wrapper
│   └── tools/
│       ├── models.ts      # Model discovery tools
│       ├── generate.ts    # Generation and queue tools
│       └── storage.ts     # File upload tools
├── dist/                  # Compiled output
├── package.json
├── tsconfig.json
└── README.md

Troubleshooting

"FAL_KEY environment variable is not set"

Make sure you've set the FAL_KEY in your MCP client configuration. The API key must be set as an environment variable.

"HTTP 401" or "Unauthorized"

Your API key may be invalid or expired. Check your API key at fal.ai/dashboard/keys.

Build Errors

Try removing node_modules and reinstalling:

rm -rf node_modules package-lock.json
npm install
npm run build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Credits

This project was inspired by the Python fal MCP server and built using:

@modelcontextprotocol/sdk - MCP TypeScript SDK
@fal-ai/client - Official fal.ai TypeScript client

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

fal.ai MCP Server

Features

Installation

Via npm (Recommended)

From Source

Configuration

Get Your API Key

Configure MCP Client

Claude Desktop

Claude Code

Cursor

Other MCP Clients

Available Tools

models

search

find

schema

generate

result

status

cancel

upload

pricing

estimate_cost

usage

analytics

Usage Examples

With Claude Desktop

Programmatic Usage

Development

Prerequisites

Setup

Project Structure

Troubleshooting

"FAL_KEY environment variable is not set"

"HTTP 401" or "Unauthorized"

Build Errors

Contributing

License

Credits

Links

`models`

`search`

`find`

`schema`

`generate`

`result`

`status`

`cancel`

`upload`

`pricing`

`estimate_cost`

`usage`

`analytics`