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

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

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

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

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

# Install to current project
uv add doubao_image_mcp_server

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

pip install doubao_image_mcp_server

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

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

1. BASE_URL (API Base Address)

• Purpose: Base API address for Doubao (Volcano Engine) platform
• Default Value: https://ark.cn-beijing.volces.com/api/v3
• Description: This is the API address for Volcano Engine platform in Beijing region, generally no need to modify
• Example: "BASE_URL": "https://ark.cn-beijing.volces.com/api/v3"

2. DOUBAO_API_KEY (API Key)

• Purpose: API key for authentication
• How to Get: Create and obtain from Volcano Engine console
• Format: Usually a UUID format string
• Note: Please keep your API key safe and do not leak it to others

3. API_MODEL_ID (Model Endpoint ID)

• Purpose: Specifies the inference endpoint ID of the image generation model to use
• How to Get: Obtained after creating an inference endpoint in Volcano Engine console
• Format: String starting with "ep-"
• Example: "API_MODEL_ID": "ep-20250528154802-c4np4"
• Description: Each inference endpoint has a unique ID to identify a specific model instance

4. IMAGE_SAVE_DIR (Image Save Directory)

• Purpose: Specifies the local directory path where generated images are saved
• Path Format: Supports both relative and absolute paths
• Absolute Path Example: "IMAGE_SAVE_DIR": "C:/images"
• Description: If the directory does not exist, the program will create it automatically

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

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

After registration, visit the Volcano Engine console:

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

1. Go to 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

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)

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)

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

This server supports use in various AI development tools, including VS Code + Cline, Cursor, Trae, etc. Configuration method is as follows:

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

VS Code + Cline:

• Find Cline extension configuration in VS Code settings
• Add the above MCP configuration to Cline's MCP server configuration

Cursor:

• Find MCP configuration options in Cursor settings
• Add the above configuration and restart Cursor

Trae:

• Add the above configuration to Trae's MCP configuration file
• Reload the configuration file after saving

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

python doubao_mcp_server.py

The server provides the following MCP tools:

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 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 specific seed to reproduce image:

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

Get a list of all available image resolutions.

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

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

The project includes a complete logging system:

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

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

• 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 MCP service
• Type Annotations: Complete type hint support

A: Visit Volcano Engine console and create a new API key in API management.

A: After creating an inference endpoint in Volcano Engine console, you can find the ID in endpoint details.

A: Currently generated images are saved in JPG format.

A: Modify the IMAGE_SAVE_DIR variable in the environment configuration.

A: Check log files and confirm that API key, model ID, and network connection are working properly.

This project is open source under the MIT License.

Welcome to submit Issues and Pull Requests to improve the project