# Quick Start Guide
Get your fal.ai MCP server running in 5 minutes!
## Step 1: Install Dependencies
```bash
cd "fal.ai mcp"
npm install
```
This installs all required packages including the MCP SDK, Smithery SDK, and TypeScript.
## Step 2: Get Your fal.ai API Key
1. Go to [fal.ai](https://fal.ai)
2. Sign up or log in
3. Navigate to your API keys section
4. Copy your API key
## Step 3: Choose Your Development Mode
### Option A: Smithery Playground (Recommended for Testing)
```bash
npm run dev
```
This will:
- Start a local development server
- Open the Smithery interactive playground in your browser
- Let you test all tools with a beautiful web interface
- Provide real-time feedback
When prompted, enter your fal.ai API key in the configuration.
### Option B: STDIO Mode (For Claude Desktop Integration)
```bash
# Build the TypeScript code
npm run build:stdio
# Run the server
FAL_KEY="your-fal-ai-api-key-here" npm run start:stdio
```
This mode is compatible with Claude Desktop and other STDIO-based MCP clients.
## Step 4: Test Your First Request
### In Smithery Playground:
Try the **search** tool with this input:
```json
{
"keywords": "flux image generation"
}
```
### In STDIO mode:
Configure your MCP client (like Claude Desktop) to use the server, then ask:
> "Search for image generation models on fal.ai"
## Step 5: Deploy to Smithery (Optional)
Want to make your server accessible via HTTP?
### 5.1 Create a GitHub Repository
```bash
# Initialize git if not already done
git init
# Add files
git add .
git commit -m "Add fal.ai MCP server"
# Push to GitHub
git remote add origin https://github.com/yourusername/fal-ai-mcp.git
git push -u origin main
```
### 5.2 Deploy on Smithery
1. Visit [smithery.ai/new](https://smithery.ai/new)
2. Click "Connect GitHub Repository"
3. Select your repository
4. Smithery will automatically detect the TypeScript runtime
5. Add your fal.ai API key in the configuration
6. Click "Deploy"
That's it! Your server is now live and accessible via HTTP! 🚀
## Common Commands
```bash
# Development
npm run dev # Start Smithery playground
# Building
npm run build # Build for production (HTTP)
npm run build:stdio # Build for STDIO mode
# Running
npm run start # Start HTTP server (after build)
npm run start:stdio # Start STDIO server (after build:stdio)
```
## Test Examples
### 1. List Available Models
```json
{
"page": 1,
"total": 10
}
```
### 2. Generate an Image
```json
{
"model": "fal-ai/flux/dev",
"parameters": {
"prompt": "A serene Japanese garden with cherry blossoms in full bloom",
"image_size": "landscape_4_3",
"num_images": 1
},
"queue": false
}
```
### 3. Upload a File
```json
{
"path": "/absolute/path/to/your/image.jpg"
}
```
### 4. Get Model Schema
```json
{
"model_id": "fal-ai/flux/dev"
}
```
## Troubleshooting
### "Cannot find module" error
```bash
npm install
```
### API Key not working
- Double-check your key is correct
- Ensure no extra spaces or quotes
- For STDIO: Make sure `FAL_KEY` environment variable is set
- For Smithery: Verify the key is entered in the web interface
### TypeScript errors
```bash
npm run build:stdio
# Check the output for specific errors
```
### Port already in use (Smithery dev)
```bash
# The CLI will automatically find an available port
# Or kill the process using the port:
lsof -ti:3000 | xargs kill -9
```
## Next Steps
- 📖 Read [README-TYPESCRIPT.md](./README-TYPESCRIPT.md) for detailed documentation
- 🔄 Check [MIGRATION_SUMMARY.md](./MIGRATION_SUMMARY.md) to understand the architecture
- 📚 Review [SMITHERY_MCP_GUIDE.md](../SMITHERY_MCP_GUIDE.md) for general Smithery patterns
- 🌐 Visit [fal.ai/docs](https://fal.ai/docs) for model-specific documentation
## Need Help?
- **Smithery Issues**: [Smithery Discord](https://smithery.ai/discord)
- **fal.ai Issues**: [fal.ai Documentation](https://fal.ai/docs)
- **MCP Protocol**: [MCP Specification](https://modelcontextprotocol.io)
Happy building! 🎉