Doubao Image Generation MCP server for AI agents

This open-source MCP server leverages the Doubao seedream-3.0-t2i model through the Volcano Engine API to generate high-quality images up to 2K resolution. It supports both Chinese and English prompts, multiple image resolutions, and precise parameter controls while being fully compatible with the Model Context Protocol.

Installation

Prerequisites

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

Installation Methods

Using uvx (Recommended)

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

Using uv to Install to Project

# Install to current project
uv add doubao_image_mcp_server

Developer Installation

# After cloning the repository
git clone https://github.com/suibin521/doubao-image-mcp-server.git
cd doubao-image-mcp-server
uv sync
# Or using pip
pip install -e .

Traditional pip Installation

pip install doubao_image_mcp_server

Configuration

This project uses environment variables passed through 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 Variables Explained

BASE_URL: Base API address for Volcano Engine platform (default: https://ark.cn-beijing.volces.com/api/v3)
DOUBAO_API_KEY: Your API key from Volcano Engine console
API_MODEL_ID: The inference endpoint ID of your model (format: ep-XXXXXXXXXXXX-XXXX)
IMAGE_SAVE_DIR: Directory path where generated images will be saved

Getting API Key and Model ID

Register on Volcano Engine Platform at https://console.volcengine.com/auth/signup
After registration, login to the Volcano Engine console
Activate the Doubao-Seedream-3.0-t2i model:
- Go to System Management → Activation Management
- Select Vision Large Model
- Find Doubao-Seedream-3.0-t2i model
- Click "Activate service"
Create an Inference Endpoint:
- Click Online inference → Create inference endpoint
- Enter a name and description
- Select the Doubao-Seedream-3.0-t2i model
- After creation, note the Model_id (format: ep-m-XXXXXXXXXXXX-XXXXX)
Create an API Key:
- Select API Key management
- Click Create API Key
- Save your API key securely

Usage

Configuring MCP Server in Development Tools

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

Starting Server Independently

python doubao_mcp_server.py

Using MCP Tools

Image Generation Tool

The main tool for generating images is doubao_generate_image with these parameters:

prompt (required): Image description text, supports Chinese and English
size (optional): Image resolution, default "1024x1024"
seed (optional): Random seed, default -1 (auto-generated)
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 with 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 an image:

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

Using in Development Tools

After configuration, you can generate images by:

In Cursor:
- Enter Agent mode
- Tell Cursor: "Please understand the available image generation tools"
- Request an image: "Please help me generate a sunset seaside landscape image"
In other development tools:
- Simply describe the image you want to generate
- The AI assistant will call the Doubao image generation tool
- Images will be saved to your configured directory

Troubleshooting

If image generation fails, check log files and verify your API key, model ID, and network connection
Generated images are saved in JPG format
To customize the save path, modify the IMAGE_SAVE_DIR variable in your configuration

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your 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"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect