SeedDream 4.0 Replicate MCP Server

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

Features

SeedDream 4.0 is a bilingual (Chinese and English) text-to-image model that excels at:

• Native 2K high resolution output with various aspect ratios
• Exceptional text layout for visually stunning results
• Accurate small and large text generation
• Photorealistic portraits with cinematic beauty
• Fast generation (3 seconds for 1K images)
• Strong instruction following and enhanced aesthetics

Available Tools

generate_image

Generate a single image from a text prompt using SeedDream 4.0 via Replicate.

Parameters:

• prompt (required): Text description of the image to generate (supports English and Chinese)
• aspect_ratio (optional): Image aspect ratio - one of: 1:1, 3:4, 4:3, 16:9, 9:16, 2:3, 3:2, 21:9, custom (default: 16:9)
• size (optional): Image size - one of: small, regular, big (default: regular)
  • small: Shortest dimension 512px
  • regular: Always 1 megapixel
  • big: Longest dimension 2048px
  • Ignored if aspect ratio is custom
• width (optional): Image width in pixels (512-2048, only used when aspect_ratio is custom)
• height (optional): Image height in pixels (512-2048, only used when aspect_ratio is custom)
• guidance_scale (optional): Prompt adherence, higher = more literal (1.0-10.0, default: 2.5)
• seed (optional): Random seed for reproducible results (0-2147483647)

Installation

Prerequisites

1. Replicate API Token: Get your API token from Replicate

   • Sign up for an account at https://replicate.com/
   • Navigate to your account settings and generate an API token
   • Keep this token secure as you'll need it for configuration

2. 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": {
    "seedream": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/seedream-v4-replicate-mcp-server.git"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your_replicate_token_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": {
    "seedream": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/PierrunoYT/seedream-v4-replicate-mcp-server.git"
      ],
      "env": {
        "REPLICATE_API_TOKEN": "r8_your_replicate_token_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:

1. Clone the repository

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

2. Install dependencies

   npm install
   

3. Build the server

   npm run build
   

4. Use absolute path in configuration

   {
     "mcpServers": {
       "seedream": {
         "command": "node",
         "args": ["/absolute/path/to/seedream-v4-replicate-mcp-server/build/index.js"],
         "env": {
           "REPLICATE_API_TOKEN": "r8_your_replicate_token_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 serene mountain landscape at sunset with a lake reflection

Specific Aspect Ratio

Create a portrait-oriented image of a futuristic cityscape (aspect ratio 9:16)

Multiple Images

Generate 3 variations of a cute robot character

Batch Generation

Generate images for these prompts: "a red rose", "a blue ocean", "a green forest"

Chinese Language Support

生成一张中国传统山水画的图片

High Guidance for Precise Results

Generate a photorealistic portrait of a person reading a book in a library (guidance scale: 7.5)

API Response Format

The server returns detailed information about generated images:

Successfully generated 1 image(s) using SeedDream 4.0:

Prompt: "a serene mountain landscape at sunset"
Aspect Ratio: 1:1
Guidance Scale: 2.5
Seed Used: 1234567890

Generated Images:
Image 1 (1024x1024): https://v3.fal.media/files/...

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

1. "REPLICATE_API_TOKEN environment variable is not set"

   • The server will continue running and show this helpful error message
   • Ensure your Replicate API token is properly set in the MCP configuration
   • Verify the token is valid and has sufficient credits
   • Note: The server no longer crashes when the API token is missing

2. "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

3. "Generation failed"

   • Check your Replicate account has sufficient credits
   • Verify your API token has the necessary permissions
   • Try with a simpler prompt to test connectivity

4. "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

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
• Graceful shutdown notifications

Pricing

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

License

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

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues related to:

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

Changelog

v0.1.1 (Latest)

• 🔧 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

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