# fal.ai MCP Server

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

Built with [FastMCP](https://github.com/jlowin/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](https://fal.ai) account with an API key

### 1. Get your fal.ai API key

Go to [fal.ai Dashboard > Keys](https://fal.ai/dashboard/keys) and create an API key.

### 2. Set up the server

```bash
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

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

## Usage with Claude Code

```bash
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`:

```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