Installation Guide

Get Fal MCP Server up and running in minutes with our comprehensive installation guide.

Prerequisites

Before you begin, ensure you have:

Python 3.10+ (for pip installation)
Claude Desktop application
Fal.ai API Key (Get one here)
Docker (optional, for containerized deployment)

Installation Methods

Method 1: Install via pip (Recommended)

The simplest way to install Fal MCP Server:

# Install the package
pip install fal-mcp-server

# Verify installation
fal-mcp --help

Method 2: Install via uv (Fastest)

Using the modern Python package manager:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Fal MCP Server
uv pip install fal-mcp-server

Method 3: Docker Installation (Recommended for Production)

✅ Docker image is now available on GitHub Container Registry!

For isolated, reproducible deployments:

# Pull the official Docker image from GitHub Packages
docker pull ghcr.io/raveenb/fal-mcp-server:latest

# Run with your API key
docker run -d \
  --name fal-mcp \
  -e FAL_KEY=your-api-key \
  -p 8080:8080 \
  ghcr.io/raveenb/fal-mcp-server:latest

# Or use docker-compose
curl -O https://raw.githubusercontent.com/raveenb/fal-mcp-server/main/docker-compose.yml
docker-compose up -d

Available Docker tags:

latest - Most recent stable release
v0.3.0, v0.2.0, etc. - Specific versions
main - Latest development build

Method 4: Install from Source

For development or customization:

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

# Install in development mode
pip install -e ".[dev]"

Configuration

Step 1: Set Your Fal.ai API Key

# Linux/macOS
export FAL_KEY="your-api-key-here"

# Windows (PowerShell)
$env:FAL_KEY="your-api-key-here"

# Or create a .env file
echo "FAL_KEY=your-api-key-here" > .env

Step 2: Configure Claude Desktop

Add the server to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Step 3: Restart Claude Desktop

After configuration, restart Claude Desktop to load the MCP server.

Transport Modes

STDIO Mode (Default)

Standard input/output mode for Claude Desktop:

fal-mcp

HTTP/SSE Mode

For web-based access:

# Start HTTP server
fal-mcp-http --host 0.0.0.0 --port 8080

# Access at http://localhost:8080/sse

Configure in Claude:

{
  "mcpServers": {
    "fal-mcp-server": {
      "command": "curl",
      "args": ["-N", "http://localhost:8080/sse"]
    }
  }
}

Dual Mode

Run both STDIO and HTTP simultaneously:

fal-mcp-dual --transport dual --port 8081

Docker Configuration

Using Docker Compose

Create a .env file:

FAL_KEY=your-api-key-here

Start the service:

docker-compose up -d

Configure Claude to connect to the Docker container:

{
  "mcpServers": {
    "fal-mcp-server": {
      "command": "curl",
      "args": ["-N", "http://localhost:8080/sse"]
    }
  }
}

Using Docker Run

The official Docker image is available on GitHub Container Registry!

# Pull the latest image (updated regularly)
docker pull ghcr.io/raveenb/fal-mcp-server:latest

# Run the container
docker run -d \
  --name fal-mcp \
  -e FAL_KEY=your-api-key \
  -p 8080:8080 \
  ghcr.io/raveenb/fal-mcp-server:latest

# Verify it's running
docker ps | grep fal-mcp

# Check logs
docker logs fal-mcp

Docker Image Features:

🔒 Non-root user for security
📦 Multi-stage build (optimized size ~150MB)
🚀 Pre-configured for production use
♻️ Automatic updates with CI/CD
🏷️ Tagged releases for version pinning

Verification

Test the Installation

Open Claude Desktop
Type: “Generate an image of a sunset”
Claude should use the generate_image tool

Check Available Tools

In Claude, ask: “What tools do you have available?”

You should see:

generate_image - Create images from text
generate_video - Create videos from images
generate_music - Generate music from descriptions

Troubleshooting

Server Not Found

If Claude doesn’t recognize the server:

Check the config file path is correct
Ensure JSON syntax is valid
Restart Claude Desktop completely

Authentication Error

If you get “FAL_KEY not set”:

Verify your API key is correct
Check environment variable is set
Ensure the key is active on Fal.ai Dashboard

Connection Issues

For HTTP mode connection problems:

Check the server is running: curl http://localhost:8080/sse
Verify firewall allows the port
Try using 127.0.0.1 instead of localhost

Advanced Configuration

Custom Models

You can specify different models in your requests:

# In Claude, you can request specific models:
"Generate an image using flux_dev model"
"Create a video with kling model"

Environment Variables

All configuration options:

Variable	Description	Default
`FAL_KEY`	Your Fal.ai API key	Required
`FAL_MCP_TRANSPORT`	Transport mode	`stdio`
`FAL_MCP_HOST`	HTTP server host	`127.0.0.1`
`FAL_MCP_PORT`	HTTP server port	`8080`
`FAL_LOG_LEVEL`	Logging level	`INFO`

Performance Tuning

For optimal performance:

# Increase timeout for long operations
export FAL_TIMEOUT=600

# Enable debug logging
export FAL_LOG_LEVEL=DEBUG

Platform-Specific Notes

macOS

Requires macOS 11+ for Claude Desktop
May need to allow network access on first run
Use Homebrew for Python: brew install python@3.11

Windows

Use PowerShell or WSL2 for best experience
Path to config: %APPDATA%\Claude\claude_desktop_config.json
May need to disable Windows Defender for Docker

Linux

Works on Ubuntu 20.04+, Debian 11+, Fedora 35+
May need to install additional dependencies: apt install python3-pip
Docker requires sudo or docker group membership

Next Steps

Now that you have Fal MCP Server installed:

View Examples - See what you can create
API Documentation - Understand the tools
Docker Guide - Advanced Docker setup
Troubleshooting - Common issues

Getting Help

If you encounter issues:

← Home Examples →