# fal.ai MCP Server (TypeScript)
A Model Context Protocol (MCP) server for interacting with fal.ai models and services, built with TypeScript and optimized for Smithery deployment with HTTP transport.
## Features
- **Model Discovery**: List and search available fal.ai models
- **Schema Inspection**: Get OpenAPI schemas for any model
- **Content Generation**: Generate content using any fal.ai model
- **Queue Management**: Support for both direct and queued model execution
- **Status Tracking**: Check status, get results, and cancel queued requests
- **File Upload**: Upload files to fal.ai CDN for use in generations
- **Dual Transport**: Supports both HTTP (Smithery) and STDIO (local) transports
## Prerequisites
- [Node.js](https://nodejs.org/) v18 or higher
- A [fal.ai API key](https://fal.ai) - Sign up and get your API key
- (Optional) [Smithery account](https://smithery.ai) for deployment
## Quick Start
### Installation
```bash
# Install dependencies
npm install
```
### Local Development with Smithery Playground
```bash
# Start the development server with interactive playground
npm run dev
```
This command starts the Smithery interactive playground where you can test all tools in real-time with a web interface.
### Local Development with STDIO
```bash
# Build the TypeScript code
npm run build:stdio
# Run with STDIO transport
FAL_KEY="your-api-key-here" npm run start:stdio
```
## Available Tools
### Model Tools
#### `models`
List available models on fal.ai with pagination support.
**Parameters:**
- `page` (optional): Page number for pagination
- `total` (optional): Number of models per page
**Example:**
```typescript
{
"page": 1,
"total": 10
}
```
#### `search`
Search for models by keywords.
**Parameters:**
- `keywords`: Search terms to find models
**Example:**
```typescript
{
"keywords": "flux image generation"
}
```
#### `schema`
Get the OpenAPI schema for a specific model.
**Parameters:**
- `model_id`: The model identifier (e.g., "fal-ai/flux/dev")
**Example:**
```typescript
{
"model_id": "fal-ai/flux/dev"
}
```
### Generation Tools
#### `generate`
Generate content using a fal.ai model.
**Parameters:**
- `model`: The model ID to use
- `parameters`: Model-specific parameters as JSON
- `queue` (optional): Use queuing system (default: false)
**Example:**
```typescript
{
"model": "fal-ai/flux/dev",
"parameters": {
"prompt": "A beautiful sunset over mountains",
"image_size": "landscape_4_3"
},
"queue": true
}
```
#### `result`
Get the result of a queued request.
**Parameters:**
- `url`: The response_url from a queued request
**Example:**
```typescript
{
"url": "https://queue.fal.run/requests/abc123/response"
}
```
#### `status`
Check the status of a queued request.
**Parameters:**
- `url`: The status_url from a queued request
**Example:**
```typescript
{
"url": "https://queue.fal.run/requests/abc123/status"
}
```
#### `cancel`
Cancel a queued request.
**Parameters:**
- `url`: The cancel_url from a queued request
**Example:**
```typescript
{
"url": "https://queue.fal.run/requests/abc123/cancel"
}
```
### Storage Tools
#### `upload`
Upload a file to fal.ai storage.
**Parameters:**
- `path`: Absolute path to the file to upload
**Example:**
```typescript
{
"path": "/path/to/image.jpg"
}
```
## Configuration
When deploying to Smithery or using the server, you'll need to provide your fal.ai API key:
### For Smithery Deployment
The server uses Zod schema for configuration validation. When connecting to the server via Smithery, you'll be prompted to provide:
- `apiKey`: Your fal.ai API key
### For STDIO Mode
Set the `FAL_KEY` environment variable:
```bash
export FAL_KEY="your-api-key-here"
```
## Development Scripts
```bash
# Start development server with Smithery playground
npm run dev
# Build for production (HTTP)
npm run build
# Build for STDIO mode
npm run build:stdio
# Start production HTTP server
npm run start
# Start STDIO server
npm run start:stdio
```
## Project Structure
```
fal.ai mcp/
├── src/
│ ├── index.ts # Main server implementation
│ ├── config.ts # Configuration constants
│ └── utils.ts # Utility functions for API requests
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── smithery.yaml # Smithery deployment configuration
└── README-TYPESCRIPT.md # This file
```
## Deployment to Smithery
1. **Push to GitHub**: Create a GitHub repository and push your code
```bash
git init
git add .
git commit -m "Initial commit"
git remote add origin <your-repo-url>
git push -u origin main
```
2. **Deploy on Smithery**:
- Visit [smithery.ai/new](https://smithery.ai/new)
- Connect your GitHub repository
- Smithery will automatically detect the TypeScript runtime
- Add your fal.ai API key in the configuration
3. **Test**: Once deployed, test your server through the Smithery interface
## Using with MCP Clients
Once deployed, you can connect to this server from any MCP-compatible client:
- **Claude Desktop**: Add the server configuration to your Claude Desktop settings
- **Cursor**: Configure in Cursor's MCP settings
- **Other MCP Clients**: Use the Smithery-provided connection URL
## API Endpoints
The server interacts with these fal.ai endpoints:
- **Base API**: `https://fal.ai/api` - Public model listing and schemas
- **Queue API**: `https://queue.fal.run` - Queued execution
- **Direct API**: `https://fal.run` - Direct execution
- **Storage API**: `https://rest.alpha.fal.ai` - File uploads
## Error Handling
All tools include comprehensive error handling:
- API errors return detailed error messages with status codes
- Network errors are caught and reported
- Invalid configurations trigger validation errors
- File upload errors include specific failure reasons
## Examples
### Generate an Image
```typescript
// Using the generate tool
{
"model": "fal-ai/flux/dev",
"parameters": {
"prompt": "A serene Japanese garden with cherry blossoms",
"image_size": "square",
"num_images": 1
},
"queue": false
}
```
### Search for Text-to-Image Models
```typescript
// Using the search tool
{
"keywords": "text-to-image stable diffusion"
}
```
### Upload and Use an Image
```typescript
// First, upload the image
{
"path": "/Users/yourname/Pictures/reference.jpg"
}
// Then use the returned file_url in a generation
{
"model": "fal-ai/flux/dev",
"parameters": {
"prompt": "Transform this image into anime style",
"image_url": "https://fal.media/files/..."
}
}
```
## Troubleshooting
### API Key Issues
If you see authentication errors:
- Verify your API key is correct
- Check that the key is properly set in your environment or Smithery config
- Ensure the key has the necessary permissions
### Build Errors
```bash
# Clear build artifacts and reinstall
rm -rf node_modules dist .smithery
npm install
npm run build
```
### STDIO Mode Not Working
Ensure you've built the TypeScript code first:
```bash
npm run build:stdio
FAL_KEY="your-key" npm run start:stdio
```
## Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
## License
MIT
## Resources
- [fal.ai Documentation](https://fal.ai/docs)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Smithery Documentation](https://smithery.ai/docs)
- [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)
