# mcp-fal

An MCP (Model Context Protocol) server that exposes [Fal.ai](https://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 |

---

## Installation

```bash
# 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):**
```json
{
  "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:**
```json
{
  "mcpServers": {
    "fal-ai": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-fal/dist/index.js"],
      "env": {
        "FAL_KEY": "fal_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### Claude Code (CLI)

```bash
claude mcp add fal-ai -- node /absolute/path/to/mcp-fal/dist/index.js --api-key fal_xxxx
```

Or with an environment variable:
```bash
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:
```json
{
  "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

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