SeedDream 4.0 FAL MCP Server

A Model Context Protocol (MCP) server that provides image generation capabilities using Bytedance's SeedDream 4.0 model via the FAL AI platform.

Features

SeedDream 4.0 is a new-generation image creation model that integrates image generation and image editing capabilities into a single, unified architecture:

Advanced Text-to-Image Generation with improved quality and detail
Flexible Image Sizing from 1024x1024 to 4096x4096 pixels
Multi-Image Generation with configurable batch sizes
Enhanced Safety Checking to filter inappropriate content
Unified Architecture combining generation and editing capabilities
High-Quality Output with superior detail and coherence
Fast Generation with optimized processing

Available Tools

`generate_image`

Generate single or multiple images from a text prompt using SeedDream 4.0.

Parameters:

prompt (required): Text description of the image to generate
image_size (optional): Image dimensions - can be:
- Presets: square_1024, square_1280, square_1536, portrait_1024, portrait_1280, landscape_1024, landscape_1280, wide_1024, tall_1024
- Custom: {width: number, height: number} (1024-4096px range)
- Default: square_1280 (1280x1280)
num_images (optional): Number of separate generations (1-6, default: 1)
max_images (optional): Maximum images per generation (1-6, default: 1)
seed (optional): Random seed for reproducible results
sync_mode (optional): Wait for upload before response (default: false)
enable_safety_checker (optional): Enable content filtering (default: true)

`generate_image_batch`

Generate multiple images with different prompts in a single request.

Parameters:

prompts (required): Array of text prompts (1-5 prompts)
image_size (optional): Size for all images (preset or custom, default: square_1280)
enable_safety_checker (optional): Enable safety checking (default: true)

Installation

Prerequisites

FAL AI API Key: Get your API key from FAL AI
- Sign up for an account at https://fal.ai/
- Navigate to your dashboard and generate an API key
- Keep this key secure as you'll need it for configuration
Node.js: Ensure you have Node.js installed (version 16 or higher)

Quick Setup (Recommended)

The easiest way to use this server is through npx, which automatically downloads and runs the latest version:

For Claude Desktop App

Add the server to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "seedream4": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/seedream-v4-fal-mcp-server.git"
      ],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      }
    }
  }
}

For Kilo Code MCP Settings

Add to your MCP settings file at: C:\Users\[username]\AppData\Roaming\Code\User\globalStorage\kilocode.kilo-code\settings\mcp_settings.json

{
  "mcpServers": {
    "seedream4": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/seedream-v4-fal-mcp-server.git"
      ],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Benefits of npx Configuration

✅ Universal Access: Works on any machine with Node.js ✅ No Local Installation: npx downloads and runs automatically ✅ Always Latest Version: Pulls from GitHub repository ✅ Cross-Platform: Windows, macOS, Linux compatible ✅ Settings Sync: Works everywhere you use your MCP client

Manual Installation (Alternative)

If you prefer to install locally:

Clone the repository

git clone https://github.com/PierrunoYT/seedream-v4-fal-mcp-server.git
cd seedream-v4-fal-mcp-server

Install dependencies
```
npm install
```
Build the server
```
npm run build
```

Use absolute path in configuration

{
  "mcpServers": {
    "seedream4": {
      "command": "node",
      "args": ["/absolute/path/to/seedream-v4-fal-mcp-server/build/index.js"],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      }
    }
  }
}

Helper script to get the absolute path:

npm run get-path

Usage Examples

Once configured, you can use the server through your MCP client:

Basic Image Generation

Generate an image of a futuristic cityscape at sunset with flying cars

Custom Image Size

Create a wide landscape image (1600x1280) of a serene mountain lake

Multiple Images

Generate 3 variations of a cute robot character (num_images: 3)

High-Resolution Generation

Create a detailed portrait in 1536x1536 resolution of a wise old wizard

Batch Generation

Generate images for these prompts: "a red rose in morning dew", "a blue ocean wave", "a green forest path"

With Custom Parameters

Generate a square image (1280x1280) of a magical forest with safety checker enabled and seed 12345

Sync Mode for Immediate Access

Create an image of a space station with sync_mode enabled for immediate download

Image Size Presets

SeedDream 4.0 supports the following preset sizes:

Square Formats:
- square_1024: 1024x1024
- square_1280: 1280x1280 (default)
- square_1536: 1536x1536
Portrait Formats:
- portrait_1024: 1024x1280
- portrait_1280: 1280x1600
Landscape Formats:
- landscape_1024: 1280x1024
- landscape_1280: 1600x1280
Special Formats:
- wide_1024: 1536x1024
- tall_1024: 1024x1536

You can also specify custom dimensions with {width: number, height: number} where both values are between 1024 and 4096 pixels.

API Response Format

The server returns detailed information about generated images:

Successfully generated 1 image(s) using SeedDream 4.0:

Prompt: "a futuristic cityscape at sunset"
Image Size: 1280x1280
Number of Images: 1
Max Images per Generation: 1
Safety Checker: Enabled
Seed Used: 1234567890

Generated Images:
Image 1 (1280x1280):
  Local Path: ./images/seedream4_futuristic_cityscape_1234567890_1_2024-01-01T12-00-00-000Z.png
  Original URL: https://storage.googleapis.com/falserverless/...

Development

Local Testing

# Test the server directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js

Watch Mode

npm run watch

Inspector Tool

npm run inspector

Troubleshooting

Common Issues

"FAL_KEY environment variable is not set"
- The server will continue running and show this helpful error message
- Ensure your FAL API key is properly set in the MCP configuration
- Verify the key is valid and has sufficient credits
- Note: The server no longer crashes when the API key is missing
"Server not showing up in Claude"
- If using npx configuration, ensure you have Node.js installed
- For manual installation, check that the absolute path is correct
- Restart Claude Desktop after configuration changes
- Verify the JSON configuration syntax is valid
"Generation failed"
- Check your FAL AI account has sufficient credits
- Verify your API key has the necessary permissions
- Try with a simpler prompt to test connectivity
- Ensure image dimensions are within the 1024-4096 range
"Invalid image size"
- Use valid presets or ensure custom dimensions are between 1024-4096
- Check that width and height are both specified for custom sizes
"npx command not found"
- Ensure Node.js is properly installed
- Try running node --version and npm --version to verify installation

Server Stability Improvements

✅ Robust Error Handling: Server continues running even without API token ✅ Graceful Shutdown: Proper handling of SIGINT and SIGTERM signals ✅ User-Friendly Messages: Clear error messages with setup instructions ✅ No More Crashes: Eliminated process.exit() calls that caused connection drops ✅ Enhanced Validation: Comprehensive input validation for all parameters

Debug Logging

The server outputs debug information to stderr, which can help diagnose issues:

Generation progress updates
Error messages with helpful instructions
API call details
Image download status
Graceful shutdown notifications

What's New in SeedDream 4.0

Improvements over SeedDream 3.0

Unified Architecture: Combines generation and editing in one model
Enhanced Quality: Improved image detail and coherence
Flexible Sizing: Support for custom dimensions up to 4096px
Multi-Image Generation: Better control over batch generation
Advanced Safety: Enhanced content filtering capabilities
Better Performance: Optimized generation pipeline

Migration from SeedDream 3.0

If you're upgrading from SeedDream 3.0:

API Endpoint: Now uses fal-ai/bytedance/seedream/v4/text-to-image
Aspect Ratios: Replaced with flexible image_size parameter
New Parameters: Added max_images, sync_mode, enable_safety_checker
Size Limits: Expanded from 2K to 4K maximum resolution
Presets: New convenient size presets for common use cases

Pricing

Image generation costs are determined by FAL AI's pricing structure. Check FAL AI Pricing for current rates.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues related to:

This MCP server: Open an issue in this repository
FAL AI API: Contact FAL AI support
SeedDream 4.0 model: Refer to FAL AI documentation

Changelog

v0.2.0 (Latest - SeedDream 4.0)

🚀 Upgraded to SeedDream 4.0: New unified architecture for generation and editing
📐 Flexible Image Sizing: Support for custom dimensions up to 4096x4096
🎯 Enhanced Presets: 9 convenient size presets for common use cases
🔒 Advanced Safety: Improved content filtering with configurable safety checker
⚡ Multi-Image Generation: Better control with num_images and max_images
🔄 Sync Mode: Option for immediate image access without CDN delays
🛡️ Enhanced Validation: Comprehensive input validation for all parameters
📊 Better Responses: More detailed generation information and status

v0.1.1 (SeedDream 3.0)

🔧 Fixed connection drops: Removed process.exit() calls that caused server crashes
🛡️ Improved error handling: Server continues running even without API token
🌍 Added portability: npx configuration works on any machine
📦 Enhanced stability: Graceful shutdown handlers and null safety checks
💬 Better user experience: Clear error messages with setup instructions
🔄 Auto-updating: npx pulls latest version from GitHub automatically

v0.1.0 (SeedDream 3.0)

Initial release with SeedDream 3.0
Support for single and batch image generation
Bilingual prompt support (English/Chinese)
Multiple aspect ratios
Configurable generation parameters

SeedDream 4.0 FAL MCP Server

A Model Context Protocol (MCP) server that provides image generation capabilities using Bytedance's SeedDream 4.0 model via the FAL AI platform.

Features

SeedDream 4.0 is a new-generation image creation model that integrates image generation and image editing capabilities into a single, unified architecture:

Advanced Text-to-Image Generation with improved quality and detail
Flexible Image Sizing from 1024x1024 to 4096x4096 pixels
Multi-Image Generation with configurable batch sizes
Enhanced Safety Checking to filter inappropriate content
Unified Architecture combining generation and editing capabilities
High-Quality Output with superior detail and coherence
Fast Generation with optimized processing

Available Tools

`generate_image`

Generate single or multiple images from a text prompt using SeedDream 4.0.

Parameters:

prompt (required): Text description of the image to generate
image_size (optional): Image dimensions - can be:
- Presets: square_1024, square_1280, square_1536, portrait_1024, portrait_1280, landscape_1024, landscape_1280, wide_1024, tall_1024
- Custom: {width: number, height: number} (1024-4096px range)
- Default: square_1280 (1280x1280)
num_images (optional): Number of separate generations (1-6, default: 1)
max_images (optional): Maximum images per generation (1-6, default: 1)
seed (optional): Random seed for reproducible results
sync_mode (optional): Wait for upload before response (default: false)
enable_safety_checker (optional): Enable content filtering (default: true)

`generate_image_batch`

Generate multiple images with different prompts in a single request.

Parameters:

prompts (required): Array of text prompts (1-5 prompts)
image_size (optional): Size for all images (preset or custom, default: square_1280)
enable_safety_checker (optional): Enable safety checking (default: true)

Installation

Prerequisites

FAL AI API Key: Get your API key from FAL AI
- Sign up for an account at https://fal.ai/
- Navigate to your dashboard and generate an API key
- Keep this key secure as you'll need it for configuration
Node.js: Ensure you have Node.js installed (version 16 or higher)

Quick Setup (Recommended)

The easiest way to use this server is through npx, which automatically downloads and runs the latest version:

For Claude Desktop App

Add the server to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "seedream4": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/seedream-v4-fal-mcp-server.git"
      ],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      }
    }
  }
}

For Kilo Code MCP Settings

Add to your MCP settings file at: C:\Users\[username]\AppData\Roaming\Code\User\globalStorage\kilocode.kilo-code\settings\mcp_settings.json

{
  "mcpServers": {
    "seedream4": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/seedream-v4-fal-mcp-server.git"
      ],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Benefits of npx Configuration

Manual Installation (Alternative)

If you prefer to install locally:

Clone the repository

git clone https://github.com/PierrunoYT/seedream-v4-fal-mcp-server.git
cd seedream-v4-fal-mcp-server

Install dependencies
```
npm install
```
Build the server
```
npm run build
```

Use absolute path in configuration

{
  "mcpServers": {
    "seedream4": {
      "command": "node",
      "args": ["/absolute/path/to/seedream-v4-fal-mcp-server/build/index.js"],
      "env": {
        "FAL_KEY": "your-fal-api-key-here"
      }
    }
  }
}

Helper script to get the absolute path:

npm run get-path

Usage Examples

Once configured, you can use the server through your MCP client:

Basic Image Generation

Generate an image of a futuristic cityscape at sunset with flying cars

Custom Image Size

Create a wide landscape image (1600x1280) of a serene mountain lake

Multiple Images

Generate 3 variations of a cute robot character (num_images: 3)

High-Resolution Generation

Create a detailed portrait in 1536x1536 resolution of a wise old wizard

Batch Generation

Generate images for these prompts: "a red rose in morning dew", "a blue ocean wave", "a green forest path"

With Custom Parameters

Generate a square image (1280x1280) of a magical forest with safety checker enabled and seed 12345

Sync Mode for Immediate Access

Create an image of a space station with sync_mode enabled for immediate download

Image Size Presets

SeedDream 4.0 supports the following preset sizes:

Square Formats:
- square_1024: 1024x1024
- square_1280: 1280x1280 (default)
- square_1536: 1536x1536
Portrait Formats:
- portrait_1024: 1024x1280
- portrait_1280: 1280x1600
Landscape Formats:
- landscape_1024: 1280x1024
- landscape_1280: 1600x1280
Special Formats:
- wide_1024: 1536x1024
- tall_1024: 1024x1536

You can also specify custom dimensions with {width: number, height: number} where both values are between 1024 and 4096 pixels.

API Response Format

The server returns detailed information about generated images:

Successfully generated 1 image(s) using SeedDream 4.0:

Prompt: "a futuristic cityscape at sunset"
Image Size: 1280x1280
Number of Images: 1
Max Images per Generation: 1
Safety Checker: Enabled
Seed Used: 1234567890

Generated Images:
Image 1 (1280x1280):
  Local Path: ./images/seedream4_futuristic_cityscape_1234567890_1_2024-01-01T12-00-00-000Z.png
  Original URL: https://storage.googleapis.com/falserverless/...

Development

Local Testing

# Test the server directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js

Watch Mode

npm run watch

Inspector Tool

npm run inspector

Troubleshooting

Common Issues

"FAL_KEY environment variable is not set"
- The server will continue running and show this helpful error message
- Ensure your FAL API key is properly set in the MCP configuration
- Verify the key is valid and has sufficient credits
- Note: The server no longer crashes when the API key is missing
"Server not showing up in Claude"
- If using npx configuration, ensure you have Node.js installed
- For manual installation, check that the absolute path is correct
- Restart Claude Desktop after configuration changes
- Verify the JSON configuration syntax is valid
"Generation failed"
- Check your FAL AI account has sufficient credits
- Verify your API key has the necessary permissions
- Try with a simpler prompt to test connectivity
- Ensure image dimensions are within the 1024-4096 range
"Invalid image size"
- Use valid presets or ensure custom dimensions are between 1024-4096
- Check that width and height are both specified for custom sizes
"npx command not found"
- Ensure Node.js is properly installed
- Try running node --version and npm --version to verify installation

Server Stability Improvements

Debug Logging

The server outputs debug information to stderr, which can help diagnose issues:

Generation progress updates
Error messages with helpful instructions
API call details
Image download status
Graceful shutdown notifications

What's New in SeedDream 4.0

Improvements over SeedDream 3.0

Unified Architecture: Combines generation and editing in one model
Enhanced Quality: Improved image detail and coherence
Flexible Sizing: Support for custom dimensions up to 4096px
Multi-Image Generation: Better control over batch generation
Advanced Safety: Enhanced content filtering capabilities
Better Performance: Optimized generation pipeline

Migration from SeedDream 3.0

If you're upgrading from SeedDream 3.0:

API Endpoint: Now uses fal-ai/bytedance/seedream/v4/text-to-image
Aspect Ratios: Replaced with flexible image_size parameter
New Parameters: Added max_images, sync_mode, enable_safety_checker
Size Limits: Expanded from 2K to 4K maximum resolution
Presets: New convenient size presets for common use cases

Pricing

Image generation costs are determined by FAL AI's pricing structure. Check FAL AI Pricing for current rates.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues related to:

This MCP server: Open an issue in this repository
FAL AI API: Contact FAL AI support
SeedDream 4.0 model: Refer to FAL AI documentation

Changelog

v0.2.0 (Latest - SeedDream 4.0)

🚀 Upgraded to SeedDream 4.0: New unified architecture for generation and editing
📐 Flexible Image Sizing: Support for custom dimensions up to 4096x4096
🎯 Enhanced Presets: 9 convenient size presets for common use cases
🔒 Advanced Safety: Improved content filtering with configurable safety checker
⚡ Multi-Image Generation: Better control with num_images and max_images
🔄 Sync Mode: Option for immediate image access without CDN delays
🛡️ Enhanced Validation: Comprehensive input validation for all parameters
📊 Better Responses: More detailed generation information and status

v0.1.1 (SeedDream 3.0)

🔧 Fixed connection drops: Removed process.exit() calls that caused server crashes
🛡️ Improved error handling: Server continues running even without API token
🌍 Added portability: npx configuration works on any machine
📦 Enhanced stability: Graceful shutdown handlers and null safety checks
💬 Better user experience: Clear error messages with setup instructions
🔄 Auto-updating: npx pulls latest version from GitHub automatically

v0.1.0 (SeedDream 3.0)

Initial release with SeedDream 3.0
Support for single and batch image generation
Bilingual prompt support (English/Chinese)
Multiple aspect ratios
Configurable generation parameters