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

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

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:

Usage Examples

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

Basic Image Generation

Specific Aspect Ratio

Multiple Images

Batch Generation

Chinese Language Support

High Guidance for Precise Results

API Response Format

The server returns detailed information about generated images:

Development

Local Testing

Watch Mode

Inspector Tool

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