# Directory Structure ``` ├── .gitignore ├── doubao_image_gen.py ├── doubao_mcp_server.py ├── images │ ├── create_api_key.jpg │ ├── create_inference_endpoint.jpg │ ├── model_activation.jpg │ └── volcengine_signup.jpg ├── LICENSE ├── pyproject.toml ├── README_CN.md ├── README.md └── uv.lock ``` # Files -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- ``` 1 | # Python 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | *.so 6 | .Python 7 | build/ 8 | develop-eggs/ 9 | dist/ 10 | downloads/ 11 | eggs/ 12 | .eggs/ 13 | lib/ 14 | lib64/ 15 | parts/ 16 | sdist/ 17 | var/ 18 | wheels/ 19 | share/python-wheels/ 20 | *.egg-info/ 21 | .installed.cfg 22 | *.egg 23 | PIPFILE.lock 24 | 25 | # PyInstaller 26 | *.manifest 27 | *.spec 28 | 29 | # Installer logs 30 | pip-log.txt 31 | pip-delete-this-directory.txt 32 | 33 | # Unit test / coverage reports 34 | htmlcov/ 35 | .tox/ 36 | .nox/ 37 | .coverage 38 | .coverage.* 39 | .cache 40 | nosetests.xml 41 | coverage.xml 42 | *.cover 43 | *.py,cover 44 | .hypothesis/ 45 | .pytest_cache/ 46 | cover/ 47 | 48 | # Translations 49 | *.mo 50 | *.pot 51 | 52 | # Environment variables 53 | .env 54 | 55 | # Log files 56 | log/ 57 | *.log 58 | 59 | # Generated images (optional, uncomment if you don't want to track generated images) 60 | # images/ 61 | # test_images/ 62 | 63 | # Django stuff: 64 | *.log 65 | local_settings.py 66 | db.sqlite3 67 | db.sqlite3-journal 68 | 69 | # Flask stuff: 70 | instance/ 71 | .webassets-cache 72 | 73 | # Scrapy stuff: 74 | .scrapy 75 | 76 | # Sphinx documentation 77 | docs/_build/ 78 | 79 | # PyBuilder 80 | .pybuilder/ 81 | target/ 82 | 83 | # Jupyter Notebook 84 | .ipynb_checkpoints 85 | 86 | # IPython 87 | profile_default/ 88 | ipython_config.py 89 | 90 | # pyenv 91 | .python-version 92 | 93 | # pipenv 94 | Pipfile.lock 95 | 96 | # poetry 97 | poetry.lock 98 | 99 | # pdm 100 | .pdm.toml 101 | 102 | # PEP 582 103 | __pypackages__/ 104 | 105 | # Celery stuff 106 | celerybeat-schedule 107 | celerybeat.pid 108 | 109 | # SageMath parsed files 110 | *.sage.py 111 | 112 | # Environments 113 | .env 114 | .venv 115 | env/ 116 | venv/ 117 | ENV/ 118 | env.bak/ 119 | venv.bak/ 120 | 121 | # Spyder project settings 122 | .spyderproject 123 | .spyproject 124 | 125 | # Rope project settings 126 | .ropeproject 127 | 128 | # mkdocs documentation 129 | /site 130 | 131 | # mypy 132 | .mypy_cache/ 133 | .dmypy.json 134 | dmypy.json 135 | 136 | # Pyre type checker 137 | .pyre/ 138 | 139 | # pytype static type analyzer 140 | .pytype/ 141 | 142 | # Cython debug symbols 143 | cython_debug/ 144 | 145 | # PyCharm 146 | .idea/ 147 | 148 | # VS Code 149 | .vscode/ 150 | 151 | # macOS 152 | .DS_Store 153 | 154 | # Windows 155 | Thumbs.db 156 | ehthumbs.db 157 | Desktop.ini 158 | 159 | # MCP specific 160 | *.log 161 | .env.local 162 | .env.production 163 | 164 | # UV specific 165 | .uv/ 166 | 167 | # Temporary files 168 | *.tmp 169 | *.temp 170 | 171 | # API Keys and secrets 172 | *.key 173 | *.pem 174 | secrets.json 175 | config.json 176 | 177 | # Generated images (documentation images are tracked) 178 | # images/ 179 | generated/ 180 | output/ 181 | ``` -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- ```markdown 1 | # Doubao Image Generation MCP Server 2 | 3 | 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. 4 | 5 | ## 1. Features 6 | 7 | - 🎨 **High-Quality Image Generation**: Based on Doubao seedream-3.0-t2i model, supports 2K resolution 8 | - 🌐 **Bilingual Support**: Prompts support both Chinese and English descriptions 9 | - 📐 **Multiple Resolutions**: Supports various resolutions from 512x512 to 2048x2048 10 | - 🎯 **Precise Control**: Supports seed, guidance scale, watermark and other parameter controls 11 | - 📁 **Local Storage**: Automatically downloads and saves generated images to specified directory 12 | - 🔧 **MCP Protocol**: Fully compatible with MCP protocol, can be integrated with MCP-supported AI assistants 13 | - 📊 **Detailed Logging**: Complete logging and error handling 14 | 15 | ## 2. Requirements 16 | 17 | - Python >= 3.13 18 | - Volcano Engine API Key 19 | - Inference Endpoint Model ID 20 | 21 | ## 3. Installation & Configuration 22 | 23 | ### 3.1 Clone Project 24 | 25 | ```bash 26 | git clone [email protected]:suibin521/doubao-image-mcp-server.git 27 | cd doubao-image-mcp-server 28 | ``` 29 | 30 | ### 3.2 Installation Methods 31 | 32 | #### Method 1: Using uvx for Direct Execution (Recommended) 33 | ```bash 34 | # Install and run directly from PyPI 35 | uvx doubao-image-mcp-server 36 | ``` 37 | 38 | #### Method 2: Using uv to Install to Project 39 | ```bash 40 | # Install to current project 41 | uv add doubao_image_mcp_server 42 | ``` 43 | 44 | #### Method 3: Developer Installation 45 | ```bash 46 | # After cloning the repository, execute in project root directory 47 | uv sync 48 | # Or using pip 49 | pip install -e . 50 | ``` 51 | 52 | #### Method 4: Traditional pip Installation 53 | ```bash 54 | pip install doubao_image_mcp_server 55 | ``` 56 | 57 | ### 3.3 Configure Environment Variables 58 | 59 | This project does not use `.env` files. All configurations are passed through the `env` field in the MCP JSON configuration file. 60 | 61 | #### 3.3.1 Environment Variable Configuration Example 62 | ```json 63 | "env": { 64 | "BASE_URL": "https://ark.cn-beijing.volces.com/api/v3", 65 | "DOUBAO_API_KEY": "your-dev-api-key-here", 66 | "API_MODEL_ID": "ep-20250528154802-c4np4", 67 | "IMAGE_SAVE_DIR": "C:/images" 68 | } 69 | ``` 70 | 71 | #### 3.3.2 Environment Variable Detailed Description 72 | 73 | **1. BASE_URL (API Base Address)** 74 | - **Purpose**: Base API address for Doubao (Volcano Engine) platform 75 | - **Default Value**: `https://ark.cn-beijing.volces.com/api/v3` 76 | - **Description**: This is the API address for Volcano Engine platform in Beijing region, generally no need to modify 77 | - **Example**: `"BASE_URL": "https://ark.cn-beijing.volces.com/api/v3"` 78 | 79 | **2. DOUBAO_API_KEY (API Key)** 80 | - **Purpose**: API key for authentication 81 | - **How to Get**: Create and obtain from Volcano Engine console 82 | - **Format**: Usually a UUID format string 83 | - **Note**: Please keep your API key safe and do not leak it to others 84 | 85 | **3. API_MODEL_ID (Model Endpoint ID)** 86 | - **Purpose**: Specifies the inference endpoint ID of the image generation model to use 87 | - **How to Get**: Obtained after creating an inference endpoint in Volcano Engine console 88 | - **Format**: String starting with "ep-" 89 | - **Example**: `"API_MODEL_ID": "ep-20250528154802-c4np4"` 90 | - **Description**: Each inference endpoint has a unique ID to identify a specific model instance 91 | 92 | **4. IMAGE_SAVE_DIR (Image Save Directory)** 93 | - **Purpose**: Specifies the local directory path where generated images are saved 94 | - **Path Format**: Supports both relative and absolute paths 95 | - **Absolute Path Example**: `"IMAGE_SAVE_DIR": "C:/images"` 96 | - **Description**: If the directory does not exist, the program will create it automatically 97 | 98 | ### 3.4 Get API Key and Model ID 99 | 100 | #### 3.4.1 Register Volcano Engine Platform 101 | 102 | 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: 103 | 104 | ``` 105 | https://console.volcengine.com/auth/signup 106 | ``` 107 | 108 |  109 | 110 | #### 3.4.2 Login to Volcano Engine Console 111 | 112 | After registration, visit the Volcano Engine console: 113 | 114 | ``` 115 | https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new 116 | ``` 117 | 118 | #### 3.4.3 Activate Image Generation Model "Doubao-Seedream-3.0-t2i" 119 | 120 | 1. Go to **System Management** → **Activation Management** interface 121 | 2. Select **Vision Large Model** 122 | 3. Find the **Doubao-Seedream-3.0-t2i** model 123 | 4. Click the **"Activate service"** button on the right to activate the service 124 | 125 | Access link: 126 | ``` 127 | https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false 128 | ``` 129 | 130 |  131 | 132 | #### 3.4.4 Create Inference Endpoint 133 | 134 | 1. In the console, click **Online inference** → **Create inference endpoint** 135 | 2. Enter the following information: 136 | - **Endpoint name**: Give your endpoint a name 137 | - **Endpoint description**: Add description information 138 | - **Model selection**: Select the **Doubao-Seedream-3.0-t2i** model you just activated 139 | 3. Click the **Create** button to create the endpoint 140 | 4. After creation, you can see the corresponding **Model_id** in the overview interface (format like: `ep-m-20250528154647-cx5fg`) 141 | 142 |  143 | 144 | #### 3.4.5 Create API Key 145 | 146 | 1. Select **API Key management** on the right side of the console 147 | 2. Click **Create API Key** 148 | 3. Generate and save your API key (please keep it safe and do not leak it) 149 | 150 |  151 | 152 | #### 3.4.6 Configuration Information Acquisition Complete 153 | 154 | After completing the above steps, you will obtain the following configuration information: 155 | - **BASE_URL**: `https://ark.cn-beijing.volces.com/api/v3` (fixed value) 156 | - **DOUBAO_API_KEY**: The API key you just created 157 | - **API_MODEL_ID**: The Model_id of the inference endpoint (like: `ep-m-20250528154647-cx5fg`) 158 | - **IMAGE_SAVE_DIR**: Image save directory path 159 | 160 | ## 4. Usage 161 | 162 | ### 4.1 Configure MCP Server in Development Tools 163 | 164 | This server supports use in various AI development tools, including VS Code + Cline, Cursor, Trae, etc. Configuration method is as follows: 165 | 166 | #### 4.1.1 MCP Configuration File Setup 167 | 168 | Add the following configuration to your MCP configuration file: 169 | 170 | ```json 171 | { 172 | "mcpServers": { 173 | "doubao_image_mcp_server": { 174 | "command": "uvx", 175 | "args": [ 176 | "doubao-image-mcp-server" 177 | ], 178 | "env": { 179 | "BASE_URL": "https://ark.cn-beijing.volces.com/api/v3", 180 | "DOUBAO_API_KEY": "your-dev-api-key-here", 181 | "API_MODEL_ID": "ep-20250528154802-c4np4", 182 | "IMAGE_SAVE_DIR": "C:/images" 183 | } 184 | } 185 | } 186 | } 187 | ``` 188 | 189 | #### 4.1.2 Development Tool Configuration Instructions 190 | 191 | **VS Code + Cline:** 192 | - Find Cline extension configuration in VS Code settings 193 | - Add the above MCP configuration to Cline's MCP server configuration 194 | 195 | **Cursor:** 196 | - Find MCP configuration options in Cursor settings 197 | - Add the above configuration and restart Cursor 198 | 199 | **Trae:** 200 | - Add the above configuration to Trae's MCP configuration file 201 | - Reload the configuration file after saving 202 | 203 | #### 4.1.3 Usage Examples 204 | 205 | After configuration, you can directly talk to the AI assistant to generate images: 206 | 207 | **Usage Example in Cursor:** 208 | 1. Enter Agent mode 209 | 2. First let Cursor understand the image generation tool: "Please understand the available image generation tools" 210 | 3. Then directly make image generation requests: "Please help me generate a sunset seaside landscape image" 211 | 212 | **Usage in Other Development Tools:** 213 | - Directly describe the image you want to generate to the AI assistant 214 | - The AI assistant will automatically call the Doubao image generation tool 215 | - Generated images will be saved to your configured directory 216 | 217 | ### 4.2 Start Server Independently 218 | 219 | ```bash 220 | python doubao_mcp_server.py 221 | ``` 222 | 223 | ### 4.3 MCP Tool Calls 224 | 225 | The server provides the following MCP tools: 226 | 227 | #### 4.3.1 `doubao_generate_image` 228 | 229 | Main tool for image generation. 230 | 231 | **Parameters:** 232 | - `prompt` (required): Image description text, supports Chinese and English 233 | - `size` (optional): Image resolution, default "1024x1024" 234 | - `seed` (optional): Random seed, if not specified, a random number will be auto-generated, default -1 235 | - `guidance_scale` (optional): Guidance scale 1.0-10.0, default 8.0 236 | - `watermark` (optional): Whether to add watermark, default true 237 | - `file_prefix` (optional): File name prefix, English only 238 | 239 | **Supported Resolutions:** 240 | - `512x512` - 512x512 (1:1 Small Square) 241 | - `768x768` - 768x768 (1:1 Square) 242 | - `1024x1024` - 1024x1024 (1:1 Large Square) 243 | - `864x1152` - 864x1152 (3:4 Portrait) 244 | - `1152x864` - 1152x864 (4:3 Landscape) 245 | - `1280x720` - 1280x720 (16:9 Widescreen) 246 | - `720x1280` - 720x1280 (9:16 Mobile Portrait) 247 | - `832x1248` - 832x1248 (2:3) 248 | - `1248x832` - 1248x832 (3:2) 249 | - `1512x648` - 1512x648 (21:9 Ultra-wide) 250 | - `2048x2048` - 2048x2048 (1:1 Ultra Large Square) 251 | 252 | **Example Calls:** 253 | 254 | Basic call (using default parameters): 255 | ```json 256 | { 257 | "tool": "doubao_generate_image", 258 | "arguments": { 259 | "prompt": "A cute orange cat sitting on a sunny windowsill, watercolor style" 260 | } 261 | } 262 | ``` 263 | 264 | Full parameter call: 265 | ```json 266 | { 267 | "tool": "doubao_generate_image", 268 | "arguments": { 269 | "prompt": "A cute orange cat sitting on a sunny windowsill, watercolor style", 270 | "size": "1024x1024", 271 | "seed": -1, 272 | "guidance_scale": 8.0, 273 | "watermark": false, 274 | "file_prefix": "cute_cat" 275 | } 276 | } 277 | ``` 278 | 279 | Using specific seed to reproduce image: 280 | ```json 281 | { 282 | "tool": "doubao_generate_image", 283 | "arguments": { 284 | "prompt": "A cute orange cat sitting on a sunny windowsill, watercolor style", 285 | "seed": 1234567890, 286 | "size": "1024x1024" 287 | } 288 | } 289 | ``` 290 | 291 | ### 4.4 MCP Resources 292 | 293 | #### 4.4.1 `resolutions` 294 | 295 | Get a list of all available image resolutions. 296 | 297 | ### 4.5 MCP Prompt Templates 298 | 299 | #### 4.5.1 `image_generation_prompt` 300 | 301 | Provides prompt templates for image generation, including all parameter descriptions and usage examples. 302 | 303 | ## 5. Project Structure 304 | 305 | ``` 306 | doubao-image-mcp-server/ 307 | ├── doubao_mcp_server.py # Main MCP server 308 | ├── doubao_image_gen.py # Core image generation tool 309 | ├── pyproject.toml # Project configuration and dependency management 310 | ├── uv.lock # Dependency lock file 311 | ├── .gitignore # Git ignore file 312 | ├── LICENSE # Open source license 313 | ├── README.md # English project documentation 314 | ├── README_CN.md # Chinese project documentation 315 | └── images/ # Documentation images directory 316 | ├── create_api_key.jpg 317 | ├── create_inference_endpoint.jpg 318 | ├── model_activation.jpg 319 | └── volcengine_signup.jpg 320 | ``` 321 | 322 | ## Logging System 323 | 324 | The project includes a complete logging system: 325 | 326 | - **File Logging**: Saved in `log/` directory 327 | - **Console Logging**: Output to stderr for debugging 328 | - **Log Levels**: DEBUG, INFO, WARNING, ERROR 329 | 330 | ## Error Handling 331 | 332 | - ✅ Environment variable validation 333 | - ✅ Parameter type and range checking 334 | - ✅ API call error handling 335 | - ✅ Image download retry mechanism 336 | - ✅ File save exception handling 337 | 338 | ## Technical Features 339 | 340 | - **Asynchronous Processing**: Async image generation based on asyncio 341 | - **Retry Mechanism**: Automatic retry for failed image downloads 342 | - **Parameter Validation**: Complete input parameter validation 343 | - **Modular Design**: Core functionality separated from MCP service 344 | - **Type Annotations**: Complete type hint support 345 | 346 | ## FAQ 347 | 348 | ### Q: How to get API key? 349 | A: Visit Volcano Engine console and create a new API key in API management. 350 | 351 | ### Q: Where to find Model ID? 352 | A: After creating an inference endpoint in Volcano Engine console, you can find the ID in endpoint details. 353 | 354 | ### Q: What image formats are supported? 355 | A: Currently generated images are saved in JPG format. 356 | 357 | ### Q: How to customize image save path? 358 | A: Modify the `IMAGE_SAVE_DIR` variable in the environment configuration. 359 | 360 | ### Q: What to do if generation fails? 361 | A: Check log files and confirm that API key, model ID, and network connection are working properly. 362 | 363 | ## License 364 | 365 | This project is open source under the MIT License. 366 | 367 | ## Contributing 368 | 369 | Welcome to submit Issues and Pull Requests to improve the project 370 | ``` -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- ```toml 1 | [project] 2 | name = "doubao_image_mcp_server" 3 | version = "1.0.1" 4 | description = "Image generation MCP server based on Doubao API" 5 | readme = "README.md" 6 | requires-python = ">=3.13" 7 | dependencies = [ 8 | "mcp>=1.0.0", 9 | "fastmcp>=0.2.0", 10 | "volcengine-python-sdk[ark]>=1.0.0", 11 | "pillow>=10.0.0", 12 | "requests>=2.31.0", 13 | ] 14 | authors = [{name = "suibin521", email = "[email protected]"}] 15 | classifiers = [ 16 | "Development Status :: 5 - Production/Stable", 17 | "Intended Audience :: Developers", 18 | "License :: OSI Approved :: MIT License", 19 | "Programming Language :: Python :: 3", 20 | "Programming Language :: Python :: 3.13", 21 | "Topic :: Software Development :: Libraries :: Python Modules", 22 | "Topic :: Scientific/Engineering :: Artificial Intelligence", 23 | "Topic :: Multimedia :: Graphics", 24 | ] 25 | 26 | [project.urls] 27 | Homepage = "https://github.com/suibin521/doubao-image-mcp-server" 28 | Repository = "https://github.com/suibin521/doubao-image-mcp-server" 29 | "Bug Tracker" = "https://github.com/suibin521/doubao-image-mcp-server/issues" 30 | Documentation = "https://github.com/suibin521/doubao-image-mcp-server#readme" 31 | 32 | [project.scripts] 33 | doubao-image-mcp-server = "doubao_mcp_server:main" 34 | 35 | [build-system] 36 | requires = ["hatchling"] 37 | build-backend = "hatchling.build" 38 | 39 | [tool.hatch.build.targets.wheel] 40 | packages = ["doubao_image_gen.py", "doubao_mcp_server.py"] 41 | 42 | [tool.hatch.build.targets.sdist] 43 | include = [ 44 | "doubao_image_gen.py", 45 | "doubao_mcp_server.py", 46 | "README.md", 47 | "README_CN.md", 48 | "LICENSE", 49 | "images/", 50 | ] 51 | exclude = [ 52 | "log/", 53 | "*.log", 54 | "__pycache__/", 55 | "*.pyc", 56 | "*.pyo", 57 | "mcp_json.md", 58 | ] 59 | ```