Seedream MCP

🚀 Seedream 4.0 MCP Tool (Enhanced Version)

This is an MCP (Model Context Protocol) toolset based on the Volcengine Seedream 4.0 API, offering features such as text-to-image generation, image-to-image generation, multi-image fusion, and sequential image generation.

Acknowledgment: This project is an enhanced development based on tengmmvp/Seedream_MCP. Thanks to the original author for their contribution!

Enhanced Features:

• ✨ Automatic upload to Qiniu Cloud and public network access
• 🎨 Prompt template system (8 preset templates)
• 📸 Support for Raycast AI Markdown image rendering
• 💾 Optimized image saving and management

✨ Features

• 🎨 Text-to-Image: Generate high-quality images based on text descriptions.
• 🖼️ Image-to-Image: Generate new images based on reference images and text instructions.
• 🎭 Multi-Image Fusion: Generate new images by fusing features from multiple reference images.
• 📚 Sequential Image Generation: Generate a sequence of related images.
• 💾 Auto-Save: Automatically download and save generated images locally to avoid URL expiration.
• ☁️ Qiniu Cloud Upload: Optional integration with Qiniu Cloud storage. Automatically upload images and generate publicly accessible URLs.
• 📝 Markdown Support: Automatically generate Markdown reference formats for images (supports Qiniu Cloud URLs and local paths).
• 🔧 Full MCP Protocol Support: Complies with the MCP standard and can be seamlessly integrated with MCP-compatible clients.
• 🖼️ Direct Image Display: Supports the MCP ImageContent type, allowing direct image preview in clients.

📦 Installation

Requirements

• Python 3.8+
• Volcengine Seedream 4.0 API key

Steps

1. Clone the project

git clone <repository-url>
cd Seedream_MCP

2. Install dependencies

pip install -e .

3. Configure environment variables

Create a .env file:

# Required configuration
ARK_API_KEY=your_api_key_here

# Optional configuration
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
SEEDREAM_MODEL_ID=doubao-seedream-4-0-250828
SEEDREAM_DEFAULT_SIZE=2K
SEEDREAM_DEFAULT_WATERMARK=false
SEEDREAM_TIMEOUT=60
SEEDREAM_API_TIMEOUT=60
SEEDREAM_MAX_RETRIES=3
LOG_LEVEL=INFO
LOG_FILE=logs/seedream_mcp.log

# Auto-save configuration
SEEDREAM_AUTO_SAVE_ENABLED=true
SEEDREAM_AUTO_SAVE_BASE_DIR=./seedream_images
SEEDREAM_AUTO_SAVE_DOWNLOAD_TIMEOUT=30
SEEDREAM_AUTO_SAVE_MAX_RETRIES=3
SEEDREAM_AUTO_SAVE_MAX_FILE_SIZE=52428800
SEEDREAM_AUTO_SAVE_MAX_CONCURRENT=5
SEEDREAM_AUTO_SAVE_DATE_FOLDER=true
SEEDREAM_AUTO_SAVE_CLEANUP_DAYS=30

# Qiniu Cloud configuration (optional, for uploading images to Qiniu Cloud storage)
QINIU_ACCESS_KEY=your_access_key
QINIU_SECRET_KEY=your_secret_key
QINIU_BUCKET_NAME=your_bucket_name
QINIU_DOMAIN=https://your-domain.com

Note: After configuring Qiniu Cloud, generated images will be automatically uploaded to Qiniu Cloud, and publicly accessible Markdown image links will be provided in the response. See Qiniu Cloud Integration Documentation for details.

4. Configure the MCP client

Add the following configuration to your MCP client configuration file:

Raycast AI / Claude Desktop / Cline, etc.

{
  "mcpServers": {
    "seedream": {
      "command": "python",
      "args": [
        "/your/path/Seedream_MCP/main.py"
      ],
      "env": {
        "ARK_BASE_URL": "https://ark.cn-beijing.volces.com/api/v3"
      }
    }
  }
}

Configuration file locations:

• Raycast AI: ~/Library/Application Support/com.raycast.macos/mcp.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cline (VSCode): .vscode/settings.json or user settings

⚠️ Important Note

• Replace /your/path/Seedream_MCP/main.py with your actual project path.
• Ensure that all dependencies are installed in your Python environment.
• Restart the MCP client after configuration.

🚀 Quick Start

Use in MCP clients (recommended)

After configuring the MCP client, you can directly generate images through natural language conversations:

Example 1: Basic text-to-image

You say:

Generate an image: A cute little dinosaur with a friendly expression, in cartoon style

AI response:

✅ Image generated successfully!

• Prompt: A cute little dinosaur with a friendly expression, in cartoon style
• Size: 2K
• Qiniu Cloud link: https://newimg.t5t6.com/seedream/...
• Local save path: seedream_images/2025-11-18/text_to_image/...

Example 2: Use a prompt template

You say:

Trendy Party, Keyword: Coca-Cola

AI response:

✅ Image generated successfully!

• Prompt: Chinese "Coca-Cola", trendy party style artistic font...
• Size: 2K (default 16:9)
• Qiniu Cloud link: https://newimg.t5t6.com/seedream/...

Example 3: WeChat official account cover

You say:

WeChat official account cover, Theme: AI technological innovation

AI response:

✅ Image generated successfully!

• Prompt: Chinese "AI technological innovation", WeChat official account cover style...
• Size: 2K (automatically uses 21:9 ratio)
• Qiniu Cloud link: https://newimg.t5t6.com/seedream/...

Available prompt templates

Simply state the template name + keyword:

Run as an MCP server

python -m seedream_mcp.server

Use in code

import asyncio
from seedream_mcp import SeedreamClient, SeedreamConfig

async def main():
    # Load configuration
    config = SeedreamConfig.from_env()

    # Create a client
    client = SeedreamClient(config)

    try:
        # Text-to-image (enable auto-save)
        result = await client.text_to_image(
            prompt="A cute little kitten, in cartoon style",
            size="2K",
            watermark=False,
            auto_save=True,
            custom_name="cute_cat"
        )
        print(f"Generated image URL: {result['image_url']}")
        print(f"Local save path: {result['local_path']}")
        print(f"Markdown reference: {result['markdown']}")

        # Image-to-image
        result = await client.image_to_image(
            prompt="Convert this image to an oil painting style",
            image="path/to/image.jpg",
            size="2K",
            auto_save=True
        )
        print(f"Converted image URL: {result['image_url']}")
        print(f"Local save path: {result['local_path']}")

    finally:
        await client.close()

if __name__ == "__main__":
    asyncio.run(main())

📚 Documentation

🎨 Prompt template system

The built-in 8 professional prompt templates allow you to generate images in corresponding styles by simply stating the template name + keyword:

• Trendy Party: Artistic fonts for operational activities.
• WeChat Official Account Cover: Automatically uses a 21:9 ratio, suitable for WeChat official account illustrations.
• Chinese Trendy Style: Combines traditional Chinese elements with modern design.
• Fresh and Artistic: Artistic and fresh style.
• Cyberpunk: Technological and futuristic style.
• New Year Festive: Festival celebration style.
• Business Simplicity: Professional business scenarios.
• Watercolor Illustration: Hand-drawn illustration style.

☁️ Automatic Qiniu Cloud upload

After configuring Qiniu Cloud, generated images will be automatically uploaded to Qiniu Cloud storage:

• ✅ Generate publicly accessible permanent links.
• ✅ Automatically generate Markdown image formats.
• ✅ Support direct image rendering in Raycast AI.
• ✅ Dual saving locally and in the cloud.

💾 Intelligent image management

• Auto-save: Automatically download images locally to avoid URL expiration.
• Date-based classification: Automatically create folders by year/month.
• Auto-cleanup: Configurable automatic cleanup of expired images.
• Concurrent download: Support concurrent download of multiple images to improve efficiency.

Tool descriptions

1. seedream_text_to_image

Generate an image based on a text description.

Parameters:

• prompt (required): Text description, recommended to be no more than 300 Chinese characters or 600 English words.
• size (optional): Image size, available values: 1K, 2K, 4K, default is 2K.
• watermark (optional): Whether to add a watermark, default is false.
• response_format (optional): Response format, available values: image, url, b64_json, default is image.
• auto_save (optional): Whether to automatically save the image locally, default uses global configuration.
• save_path (optional): Custom save path, uses the default path if not specified.
• custom_name (optional): Custom file name prefix.

Natural language example:

Generate an image: A cute little kitten, in cartoon style

Or use a prompt template:

Trendy Party, Keyword: Coca-Cola

2. seedream_image_to_image

Generate a new image based on a reference image and text instructions.

Parameters:

• prompt (required): Image editing instructions.
• image (required): Reference image URL or local file path.
• size (optional): Output image size, default is 2K.
• watermark (optional): Whether to add a watermark, default is false.
• response_format (optional): Response format, available values: image, url, b64_json, default is image.
• auto_save (optional): Whether to automatically save the image locally, default uses global configuration.
• save_path (optional): Custom save path, uses the default path if not specified.
• custom_name (optional): Custom file name prefix.

Example:

{
  "prompt": "Convert this image to an oil painting style",
  "image": "https://example.com/image.jpg",
  "size": "2K",
  "watermark": false,
  "auto_save": true,
  "custom_name": "oil_painting"
}

3. seedream_multi_image_fusion

Generate a new image by fusing features from multiple reference images.

Parameters:

• prompt (required): Fusion instruction description.
• images (required): Array of multiple reference image URLs or file paths (2 - 5 images).
• size (optional): Output image size, default is 2K.
• auto_save (optional): Whether to automatically save the image locally, default uses global configuration.
• save_path (optional): Custom save path, uses the default path if not specified.
• custom_name (optional): Custom file name prefix.

Example:

{
  "prompt": "Fuse these images into an artistic work",
  "images": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg",
    "https://example.com/image3.jpg"
  ],
  "size": "4K",
  "auto_save": true,
  "custom_name": "fusion_art"
}

4. seedream_sequential_generation

Generate a sequence of related images.

Parameters:

• prompt (required): Description for sequential image generation.
• max_images (optional): Maximum number of images (1 - 10), default is 3.
• images (optional): Array of reference images.
• size (optional): Image size, default is 2K.
• auto_save (optional): Whether to automatically save the images locally, default uses global configuration.
• save_path (optional): Custom save path, uses the default path if not specified.
• custom_name (optional): Custom file name prefix.

Example:

{
  "prompt": "Science fiction city landscape, futuristic style",
  "max_images": 4,
  "size": "2K",
  "auto_save": true,
  "custom_name": "sci_fi_city"
}

Configuration options

Auto-save function

The auto-save function solves the problem of generated image URLs expiring after 24 hours, providing permanent local image storage.

Core features

• Auto-download: Automatically download generated images to a specified local directory.
• Intelligent naming: Use a naming rule of timestamp + content hash + size information.
• Directory management: Automatically classify and store by tool type and date.
• Markdown support: Automatically generate Markdown reference formats for local images.
• Error recovery: Provide the original URL as an alternative in case of download failure.
• Concurrent download: Support concurrent download processing of batch images.

Usage example

# Text-to-image with auto-save enabled
result = await client.text_to_image(
    prompt="A beautiful landscape painting",
    auto_save=True,
    custom_name="landscape"
)

# The returned result contains:
# - image_url: Original image URL
# - local_path: Local save path
# - markdown: Markdown reference format
# - save_result: Detailed information about the save operation

File organization structure

images/
├── 2024-01-15/
│ ├── text_to_image/
│ │ ├── landscape_20240115_143022_abc123_2K.png
│ │ └── portrait_20240115_143045_def456_4K.png
│ ├── image_to_image/
│ │ └── style_transfer_20240115_144001_ghi789_2K.png
│ └── multi_image_fusion/
│ └── fusion_art_20240115_145030_jkl012_4K.png
└── 2024-01-16/
└── ...

Configuration instructions

• SEEDREAM_AUTO_SAVE_ENABLED: Globally enable/disable auto-save.
• SEEDREAM_AUTO_SAVE_BASE_DIR: Root directory for image saving.
• SEEDREAM_AUTO_SAVE_DATE_FOLDER: Whether to create subfolders by date.
• SEEDREAM_AUTO_SAVE_MAX_FILE_SIZE: Limit the maximum file size for download.
• SEEDREAM_AUTO_SAVE_MAX_CONCURRENT: Control the number of concurrent downloads.
• SEEDREAM_AUTO_SAVE_CLEANUP_DAYS: Automatically clean up old files older than the specified number of days.

Error handling

The tool provides a complete error handling mechanism:

• Parameter validation errors: Check required parameters and parameter formats.
• API call errors: Handle network errors, timeouts, etc.
• Authentication errors: Invalid or expired API keys.
• Quota errors: Exceeded API call limits.
• Server errors: Volcengine service exceptions.

Logging

The tool supports detailed logging:

• Function call logs
• API request and response logs
• Error and exception logs
• Performance monitoring logs

The log level can be configured through the LOG_LEVEL environment variable.

Development and testing

Run tests

# Run integration tests
python tests/test_mcp_integration.py

# Run verification scripts
python verify_installation.py

Project structure

Seedream_MCP/
├── seedream_mcp/           # Main code
│   ├── __init__.py
│   ├── client.py           # API client
│   ├── config.py           # Configuration management
│   ├── server.py           # MCP server
│   ├── tools/              # Tool implementations
│   └── utils/              # Utility functions
├── docs/                   # Documentation directory
├── tests/                  # Test files
├── examples/               # Usage examples
├── verifys/                # Verification scripts
├── .env.example           # Environment variable example
├── main.py                # Main program entry
├── requirements.txt       # Dependency list
└── README.md             # Instruction document

Frequently Asked Questions

Q: Images don't display in Raycast AI?

A: Ensure that:

1. Qiniu Cloud is configured (images require publicly accessible URLs).
2. The Qiniu Cloud domain name is configured correctly.
3. Restart Raycast AI.

Q: How to turn off the watermark?

A: Set the following in the .env file:

SEEDREAM_DEFAULT_WATERMARK=false

Q: Where are the images saved?

A: By default, they are saved in the ./seedream_images/ directory, classified by date and function:

seedream_images/
├── 2025-11-18/
│   ├── text_to_image/
│   ├── image_to_image/
│   └── multi_image_fusion/

Q: How to use prompt templates?

A: Simply state the template name + keyword:

Trendy Party, Keyword: Coca-Cola
WeChat Official Account Cover, Theme: AI technological innovation
Chinese Trendy Style, Theme: Mid-Autumn Festival

Contribution

Contributions to the code, reporting issues, or suggesting improvements are welcome!

Contribution methods

1. Fork this repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

Development guidelines

• Follow the existing code style.
• Add necessary tests.
• Update relevant documentation.
• Ensure that all tests pass.

Acknowledgments

• Thanks to tengmmvp/Seedream_MCP for providing the original project.
• Thanks to Volcengine for providing the Seedream 4.0 API.
• Thanks to Qiniu Cloud for providing cloud storage services.

📄 License

This project is licensed under the MIT license. See the LICENSE file for details.

Contact

• GitHub Issues: https://github.com/joeseesun/Seedream_MCP/issues
• Original project: https://github.com/tengmmvp/Seedream_MCP

⭐ If this project is helpful to you, please give it a Star!