Doubao Image MCP Server

🚀 Doubao Image Generation MCP Server

An image generation MCP server based on the FastMCP framework and Volcano Engine API. It supports high-quality image generation through the Doubao (doubao-seedream-3.0-t2i) model.

🚀 Quick Start

This server is an image generation MCP server relying on the FastMCP framework and Volcano Engine API. With the support of the Doubao (doubao-seedream-3.0-t2i) model, it can generate high - quality images. You can follow the installation and configuration steps below to use it.

✨ Features

• 🎨 High - Quality Image Generation: Based on the Doubao seedream - 3.0 - t2i model, it supports 2K resolution.
• 🌐 Bilingual Support: Prompts support both Chinese and English descriptions.
• 📐 Multiple Resolutions: Supports various resolutions from 512x512 to 2048x2048.
• 🎯 Precise Control: Supports parameter controls such as seed, guidance scale, and watermark.
• 📁 Local Storage: Automatically downloads and saves generated images to the specified directory.
• 🔧 MCP Protocol: Fully compatible with the MCP protocol and can be integrated with AI assistants that support MCP.
• 📊 Detailed Logging: Has complete logging and error - handling mechanisms.

📦 Installation

Requirements

• Python >= 3.13
• Volcano Engine API Key
• Inference Endpoint Model ID

Clone Project

git clone git@github.com:suibin521/doubao-image-mcp-server.git
cd doubao-image-mcp-server

Installation Methods

Method 1: Using uvx for Direct Execution (Recommended)

# Install and run directly from PyPI
uvx doubao-image-mcp-server

Method 2: Using uv to Install to Project

# Install to current project
uv add doubao_image_mcp_server

Method 3: Developer Installation

# After cloning the repository, execute in project root directory
uv sync
# Or using pip
pip install -e .

Method 4: Traditional pip Installation

pip install doubao_image_mcp_server

Configure Environment Variables

This project does not use .env files. All configurations are passed through the env field in the MCP JSON configuration file.

Environment Variable Configuration Example

"env": {
  "BASE_URL": "https://ark.cn-beijing.volces.com/api/v3",
  "DOUBAO_API_KEY": "your-dev-api-key-here",
  "API_MODEL_ID": "ep-20250528154802-c4np4",
  "IMAGE_SAVE_DIR": "C:/images"
}

Environment Variable Detailed Description

Get API Key and Model ID

Register Volcano Engine Platform

Use the following URL to log in to the Volcano platform and register. You can select the language (Chinese or English) in the upper right corner:

https://console.volcengine.com/auth/signup

Login to Volcano Engine Console

After registration, visit the Volcano Engine console:

https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new

Activate Image Generation Model "Doubao - Seedream - 3.0 - t2i"

1. Go to the System Management → Activation Management interface.
2. Select Vision Large Model.
3. Find the Doubao - Seedream - 3.0 - t2i model.
4. Click the "Activate service" button on the right to activate the service. Access link:

https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false

Create Inference Endpoint

1. In the console, click Online inference → Create inference endpoint.
2. Enter the following information:
   • Endpoint name: Give your endpoint a name.
   • Endpoint description: Add description information.
   • Model selection: Select the Doubao - Seedream - 3.0 - t2i model you just activated.
3. Click the Create button to create the endpoint.
4. After creation, you can see the corresponding Model_id in the overview interface (format like: ep - m - 20250528154647 - cx5fg).

Create API Key

1. Select API Key management on the right side of the console.
2. Click Create API Key.
3. Generate and save your API key (please keep it safe and do not leak it).

Configuration Information Acquisition Complete

After completing the above steps, you will obtain the following configuration information:

• BASE_URL: https://ark.cn-beijing.volces.com/api/v3 (fixed value)
• DOUBAO_API_KEY: The API key you just created
• API_MODEL_ID: The Model_id of the inference endpoint (like: ep - m - 20250528154647 - cx5fg)
• IMAGE_SAVE_DIR: Image save directory path

💻 Usage Examples

Configure MCP Server in Development Tools

This server supports use in various AI development tools, including VS Code + Cline, Cursor, Trae, etc.

MCP Configuration File Setup

Add the following configuration to your MCP configuration file:

{
  "mcpServers": {
    "doubao_image_mcp_server": {
      "command": "uvx",
      "args": [
        "doubao-image-mcp-server"
      ],
      "env": {
        "BASE_URL": "https://ark.cn-beijing.volces.com/api/v3",
        "DOUBAO_API_KEY": "your-dev-api-key-here",
        "API_MODEL_ID": "ep-20250528154802-c4np4",
        "IMAGE_SAVE_DIR": "C:/images"
      }
    }
  }
}

Development Tool Configuration Instructions

• VS Code + Cline: Find the Cline extension configuration in VS Code settings and add the above MCP configuration to Cline's MCP server configuration.
• Cursor: Find the MCP configuration options in Cursor settings, add the above configuration, and restart Cursor.
• Trae: Add the above configuration to Trae's MCP configuration file and reload the configuration file after saving.

Usage Examples

After configuration, you can directly talk to the AI assistant to generate images.

• Usage Example in Cursor:
  1. Enter Agent mode.
  2. First, let Cursor understand the image generation tool: "Please understand the available image generation tools".
  3. Then, directly make image generation requests: "Please help me generate a sunset seaside landscape image".
• Usage in Other Development Tools:
  • Directly describe the image you want to generate to the AI assistant.
  • The AI assistant will automatically call the Doubao image generation tool.
  • Generated images will be saved to your configured directory.

Start Server Independently

python doubao_mcp_server.py

MCP Tool Calls

doubao_generate_image

The main tool for image generation.

• Parameters:

  • prompt (required): Image description text, supports Chinese and English.
  • size (optional): Image resolution, default "1024x1024".
  • seed (optional): Random seed. If not specified, a random number will be auto - generated, default - 1.
  • guidance_scale (optional): Guidance scale 1.0 - 10.0, default 8.0.
  • watermark (optional): Whether to add a watermark, default true.
  • file_prefix (optional): File name prefix, English only.

• Supported Resolutions:

  • 512x512 - 512x512 (1:1 Small Square)
  • 768x768 - 768x768 (1:1 Square)
  • 1024x1024 - 1024x1024 (1:1 Large Square)
  • 864x1152 - 864x1152 (3:4 Portrait)
  • 1152x864 - 1152x864 (4:3 Landscape)
  • 1280x720 - 1280x720 (16:9 Widescreen)
  • 720x1280 - 720x1280 (9:16 Mobile Portrait)
  • 832x1248 - 832x1248 (2:3)
  • 1248x832 - 1248x832 (3:2)
  • 1512x648 - 1512x648 (21:9 Ultra - wide)
  • 2048x2048 - 2048x2048 (1:1 Ultra Large Square)

• Example Calls:

  • Basic call (using default parameters):

{
  "tool": "doubao_generate_image",
  "arguments": {
    "prompt": "A cute orange cat sitting on a sunny windowsill, watercolor style"
  }
}

- **Full parameter call**:

{
  "tool": "doubao_generate_image",
  "arguments": {
    "prompt": "A cute orange cat sitting on a sunny windowsill, watercolor style",
    "size": "1024x1024",
    "seed": -1,
    "guidance_scale": 8.0,
    "watermark": false,
    "file_prefix": "cute_cat"
  }
}

- **Using a specific seed to reproduce an image**:

{
  "tool": "doubao_generate_image",
  "arguments": {
    "prompt": "A cute orange cat sitting on a sunny windowsill, watercolor style",
    "seed": 1234567890,
    "size": "1024x1024"
  }
}

resolutions

Get a list of all available image resolutions.

image_generation_prompt

Provides prompt templates for image generation, including all parameter descriptions and usage examples.

📚 Documentation

Project Structure

doubao-image-mcp-server/
├── doubao_mcp_server.py    # Main MCP server
├── doubao_image_gen.py     # Core image generation tool
├── pyproject.toml          # Project configuration and dependency management
├── uv.lock                 # Dependency lock file
├── .gitignore             # Git ignore file
├── LICENSE                # Open source license
├── README.md              # English project documentation
├── README_CN.md           # Chinese project documentation
└── images/                # Documentation images directory
    ├── create_api_key.jpg
    ├── create_inference_endpoint.jpg
    ├── model_activation.jpg
    └── volcengine_signup.jpg

Logging System

The project includes a complete logging system:

• File Logging: Saved in the log/ directory.
• Console Logging: Output to stderr for debugging.
• Log Levels: DEBUG, INFO, WARNING, ERROR.

Error Handling

• ✅ Environment variable validation
• ✅ Parameter type and range checking
• ✅ API call error handling
• ✅ Image download retry mechanism
• ✅ File save exception handling

Technical Features

• Asynchronous Processing: Async image generation based on asyncio.
• Retry Mechanism: Automatic retry for failed image downloads.
• Parameter Validation: Complete input parameter validation.
• Modular Design: Core functionality separated from the MCP service.
• Type Annotations: Complete type hint support.

FAQ

• Q: How to get an API key? A: Visit the Volcano Engine console and create a new API key in API management.
• Q: Where to find the Model ID? A: After creating an inference endpoint in the Volcano Engine console, you can find the ID in the endpoint details.
• Q: What image formats are supported? A: Currently, generated images are saved in JPG format.
• Q: How to customize the image save path? A: Modify the IMAGE_SAVE_DIR variable in the environment configuration.
• Q: What to do if generation fails? A: Check the log files and confirm that the API key, model ID, and network connection are working properly.

📄 License

This project is open source under the MIT License.

Contributing

Welcome to submit Issues and Pull Requests to improve the project.