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

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
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:

Clone the repository

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

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

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

"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
"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 Replicate account has sufficient credits
- Verify your API token has the necessary permissions
- Try with a simpler prompt to test connectivity
"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

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