Seedream MCP

🚀 MCP Doubao Seedream 4.0 - Doubao Image Generation MCP Server

This is a text-to-image server based on the Doubao Seedream 4.0 model using the Model Context Protocol (MCP). It can be directly integrated into Claude Code for use.

✨ Features

• 🎨 AI Image Generation: Generate images from text based on the Doubao Seedream model.
• 📁 Automatic Download: Automatically download generated images to a specified directory.
• 🔧 Flexible Configuration: Support various image sizes, watermark control, and batch generation.
• 🚀 Plug-and-Play: Seamlessly integrate into Claude Code via the MCP protocol.
• 💾 Local Storage: Save images locally for future use.

🚀 Quick Start

1. Environment Requirements

• Python 3.11+
• uv (recommended) or pip
• Claude Code

2. Installation

# Clone the project
git clone <your-repo-url>
cd seedream_mcp

# Method 1: Use uv (recommended)
uv sync

# Method 2: Use pip
pip install -r requirements.txt

Note: The requirements.txt file is generated by the following command:

uv export --format requirements.txt --output-file requirements.txt

3. Configuration

You can obtain the ARK_API_KEY from the Volcengine Ark console (https://www.volcengine.com/product/ark).

Set the environment variable for the Doubao API key:

export ARK_API_KEY="your-api-key-here"

Or set it in the Claude Code configuration:

{
  "mcpServers": {
    "mcp-doubao": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_doubao.server"],
      "cwd": "/path/to/your/seedream_mcp",
      "env": {
        "ARK_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. Test Run

# Test the server
uv run python -m mcp_doubao.server

# Test image generation (optional)
uv run python -c "
import asyncio
import sys
sys.path.append('src')
from mcp_doubao.tools import handle_generate_images

async def test():
    result = await handle_generate_images({
        'prompt': 'A cute kitten',
        'output_dir': './test_images'
    })
    print(result[0].text)

asyncio.run(test())
"

5. Integration with Claude Code

For detailed integration steps, please refer to INTEGRATION_GUIDE.md.

Method 1: Use the startup script (recommended)

Use the startup script provided by the project to automatically set up the virtual environment and Python path:

{
  "mcpServers": {
    "mcp-doubao": {
      "type": "stdio",
      "command": "/path/to/your/seedream_mcp/start_mcp_server.sh",
      "env": {
        "ARK_API_KEY": "your-api-key-here"
      }
    }
  }
}

Method 2: Use the uv command

claude mcp add-json mcp-doubao '{
  "type": "stdio",
  "command": "uv",
  "args": ["run", "python", "-m", "mcp_doubao.server"],
  "cwd": "/path/to/your/seedream_mcp",
  "env": {
    "ARK_API_KEY": "your-api-key-here"
  }
}'

💻 Usage Examples

Basic Usage

In Claude Code, directly make requests in natural language:

Please generate an image of cherry blossoms flying.

Advanced Parameters

Generate 3 landscape paintings in different styles, with 4K resolution, save them to the artwork folder, and do not add watermarks.

Tool Parameters

📚 Documentation

Project Structure

seedream_mcp/
├── src/mcp_doubao/
│   ├── __init__.py          # Module initialization
│   ├── server.py            # MCP server entry point
│   ├── tools.py             # Tool definition and processing
│   ├── doubao_client.py     # Doubao API client
│   ├── downloader.py        # Image downloader
│   ├── config.py            # Configuration constants
│   └── types.py             # Data type definitions
├── start_mcp_server.sh      # Claude Code startup script (recommended)
├── scripts/
│   └── run_stdio.sh         # Alternative startup script
├── examples/
│   └── prompts.txt          # Example prompts
├── tests/                   # Test files
├── .venv/                   # Python virtual environment
├── pyproject.toml          # Project configuration
├── README.md               # Project description
└── INTEGRATION_GUIDE.md    # Integration guide

Technical Implementation

MCP Protocol

It is implemented based on Model Context Protocol 1.14.1+ to provide standardized tool interfaces.

API Integration

• SDK: volcengine-python-sdk[ark] 4.0.21+
• Model: doubao-seedream-4-0-250828
• Endpoint: https://ark.cn-beijing.volces.com/api/v3

Image Download

• HTTP Client: httpx 0.28.1+
• File Naming: image_001.jpeg, image_002.jpeg... (automatically avoid overwriting)
• Format Support: JPEG, PNG, WebP, etc.
• Anti-Overwriting: Automatically add a numeric suffix if the file already exists.

Development Instructions

Startup Script Features

The start_mcp_server.sh script has the following features:

• Automatic Environment Setup: Automatically use the project's .venv virtual environment.
• Path Configuration: Automatically set PYTHONPATH to the project's src directory.
• Working Directory: Automatically switch to the project root directory.
• Environment Variables: The ARK_API_KEY can be passed through the Claude Code configuration.

Local Development

# Use the startup script (recommended)
./start_mcp_server.sh

# Or use the uv command
uv run python -m mcp_doubao.server

# Run tests
uv run python -m pytest tests/

# Code formatting
uv run ruff format src/

# Update requirements.txt (after adding new dependencies)
uv export --format requirements.txt --output-file requirements.txt

Extended Functionality

The existing architecture supports easy extension:

• Add new image parameters (guidance parameters, seeds, etc.).
• Support image-to-image generation.
• Add database records.
• Add quota management.

Troubleshooting

Common Issues

1. Import Errors: Ensure that all dependencies are correctly installed.
2. API Errors: Check if the ARK_API_KEY environment variable is correctly set.
3. Permission Errors: Ensure that the output directory has write permissions.
4. Image Overwriting: The system automatically avoids overwriting existing images and generates unique file names.

Debug Mode

# Enable detailed logging
PYTHONPATH=src uv run python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
# ... Your test code
"

Dependencies

Core dependencies:

• mcp>=1.14.1 - Model Context Protocol
• volcengine-python-sdk[ark]>=4.0.21 - Doubao API SDK
• httpx>=0.28.1 - HTTP client

📄 License

This project is open-source under the MIT License.

🤝 Contribution

Welcome to submit Issues and Pull Requests!

📝 Changelog

v0.1.0 (2024-09-23)

• ✨ Initial version released.
• 🎨 Support basic image generation functionality.
• 📁 Automatic image download.
• 🔧 MCP protocol integration.
• 💾 Local file storage.