豆瓣图像生成MCP服务器
一个基于FastMCP框架和火山引擎API的图像生成MCP服务器，支持通过豆宝（豆宝-种子-3.0-t2i）模型生成高质量图像。
1.特点
- 🎨 高质量图像生成：基于豆瓣seedream-3.0-t2i模型，支持2K分辨率
- 🌐 双语支持：提示支持中英文描述
- 📐 多分辨率：支持从512x512到2048x2048的各种分辨率
- 🎯 精确控制：支持种子、引导比例、水印和其他参数控制
- 📁 本地存储：自动下载生成的图像并将其保存到指定目录
- 🔧 MCP协议：与MCP协议完全兼容，可与MCP支持的AI助手集成
- 📊 详细日志记录：完整的日志记录和错误处理
2.要求
- Python>=3.13
- 火山引擎API密钥
- 推理端点模型ID
3.安装与配置
3.1克隆项目
git clone git@github.com:suibin521/doubao-image-mcp-server.git
cd doubao-image-mcp-server3.2安装方法
方法1：使用uvx直接执行（推荐）
# Install and run directly from PyPI
uvx doubao-image-mcp-server方法2：使用uv安装到项目中
# Install to current project
uv add doubao_image_mcp_server方法3：开发人员安装
# After cloning the repository, execute in project root directory
uv sync
# Or using pip
pip install -e .方法4：传统管道安装
pip install doubao_image_mcp_server3.3配置环境变量
此项目不使用 .env 文件夹。所有配置都通过 env MCP JSON配置文件中的字段。
3.3.1环境变量配置示例
"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.3.2环境变量详细说明
1.BASE_URL（API基址）
- 目的：豆宝（火山引擎）平台API基础地址
- 默认值:
https://ark.cn-beijing.volces.com/api/v3 - 描述：这是北京地区火山引擎平台的API地址，一般无需修改
- 示例:
"BASE_URL": "https://ark.cn-beijing.volces.com/api/v3"
2.DOUBAO_API_KEY（API密钥）
- 目的：用于身份验证的API密钥
- 如何获得：从火山引擎控制台创建和获取
- 格式：通常为UUID格式字符串
- 备注：请保管好您的API密钥，不要泄露给他人
3.API_MODEL_ID（模型端点ID）
- 目的：指定要使用的图像生成模型的推理端点ID
- 如何获得：在Volcano引擎控制台中创建推理端点后获得
- 格式：以“ep-”开头的字符串
- 示例:
"API_MODEL_ID": "ep-20250528154802-c4np4" - 描述：每个推理端点都有一个唯一的ID来标识特定的模型实例
4.IMAGE_SAVE_DIR（图像保存目录）
- 目的：指定保存生成图像的本地目录路径
- 路径格式：支持相对路径和绝对路径
- 绝对路径示例:
"IMAGE_SAVE_DIR": "C:/images" - 描述：如果目录不存在，程序将自动创建它
3.4获取API密钥和型号ID
3.4.1注册火山发动机平台
使用以下URL登录Volcano平台并注册。您可以在右上角选择语言（中文或英文）：
https://console.volcengine.com/auth/signupRegister Volcano Engine Platform
3.4.2登录火山发动机控制台
注册后，请访问Volcano Engine控制台：
https://console.volcengine.com/ark/region:ark+cn-beijing/overview?briefPage=0&briefType=introduce&type=new3.4.3激活图像生成模型“Doubao-Seedream-3.0-t2i”
- 首选 系统管理 → 激活管理 接口
- 选择 视觉大模型
- 查找 豆瓣-种子-3.0-t2i 模型
- 点击 “激活服务” 右侧的按钮用于激活服务
访问链接：
https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false
3.4.4创建推理端点
- 在控制台中，单击 在线推理 → 创建推理端点
- 输入以下信息：
- 端点名称：为端点命名 - 端点描述：添加描述信息 - 模型选择：选择 豆瓣-种子-3.0-t2i 您刚刚激活的模型
- 点击 创建 创建端点的按钮
- 创建后，您可以看到相应的 型号_id 在概述界面中（格式如下：
ep-m-20250528154647-cx5fg)
3.4.5创建API密钥
- 选择 API密钥管理 在控制台的右侧
- 点击 创建API密钥
- 生成并保存您的API密钥（请保持安全，不要泄露）
3.4.6配置信息采集完成
完成上述步骤后，您将获得以下配置信息：
- BASE_URL:
https://ark.cn-beijing.volces.com/api/v3（固定值） - DOUBAO_API_键：您刚才创建的API密钥
- API模式ID：推理端点的Model_id（例如：
ep-m-20250528154647-cx5fg) - IMAGE_SAVE_DIR：图像保存目录路径
4.使用方法
4.1在开发工具中配置MCP服务器
该服务器支持在各种AI开发工具中使用，包括VS Code+Cline、Cursor、Trae等。配置方法如下：
4.1.1 MCP配置文件设置
将以下配置添加到MCP配置文件中：
{
"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"
}
}
}
}4.1.2开发工具配置说明
VS代码+临床：
- 在VS代码设置中查找Cline扩展配置
- 将上述MCP配置添加到Cline的MCP服务器配置中
光标：
- 在游标设置中查找MCP配置选项
- 添加上述配置并重新启动Cursor
带来：
- 将上述配置添加到Trae的MCP配置文件中
- 保存后重新加载配置文件
4.1.3使用示例
配置后，您可以直接与AI助手对话以生成图像：
游标中的使用示例：
- 进入代理模式
- 首先让Cursor了解一下图像生成工具：“请了解可用的图像生成工具”
- 然后直接发出图像生成请求：“请帮我生成一张日落海滨景观图像”
在其他开发工具中的使用：
- 直接向AI助手描述您想要生成的图像
- AI助手会自动调用豆瓣图像生成工具
- 生成的图像将保存到您配置的目录中
4.2独立启动服务器
python doubao_mcp_server.py4.3 MCP工具调用
服务器提供以下MCP工具：
4.3.1 doubao_generate_image
图像生成的主要工具。
参数：
prompt（必填）：图片描述文本，支持中英文size（可选）：图像分辨率，默认为“1024x1024”seed（可选）：随机种子，如果未指定，将自动生成随机数，默认为-1guidance_scale（可选）：制导刻度1.0-10.0，默认8.0watermark（可选）：是否添加水印，默认为truefile_prefix（可选）：文件名前缀，仅限英文
支持的决议：
512x512-512x512（1:1小方块）768x768-768x768（1:1正方形）1024x1024-1024x1024（1:1大正方形）864x1152-864x1152（3:4肖像）1152x864-1152x864（4:3景观）1280x720-1280x720（16:9宽屏）720x1280-720x1280（9:16移动肖像）832x1248-832x1248（2:3）1248x832-1248x832（3:2）1512x648-1512x648（21:9超宽）2048x2048-2048x2048（1:1超大广场）
示例调用：
基本调用（使用默认参数）：
{
"tool": "doubao_generate_image",
"arguments": {
"prompt": "A cute orange cat sitting on a sunny windowsill, watercolor style"
}
}完整参数调用：
{
"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"
}
}使用特定种子复制图像：
{
"tool": "doubao_generate_image",
"arguments": {
"prompt": "A cute orange cat sitting on a sunny windowsill, watercolor style",
"seed": 1234567890,
"size": "1024x1024"
}
}4.4 MCP资源
4.4.1 resolutions
获取所有可用图像分辨率的列表。
4.5 MCP提示模板
4.5.1 image_generation_prompt
提供图像生成的提示模板，包括所有参数说明和使用示例。
5.项目结构
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记录系统
该项目包括一个完整的测井系统：
- 文件记录：保存在
log/目录 - 控制台的日志：输出到stderr进行调试
- 日志级别：调试、信息、警告、错误
错误处理
- ✅ 环境变量验证
- ✅ 参数类型和范围检查
- ✅ API调用错误处理
- ✅ 图像下载重试机制
- ✅ 文件保存异常处理
技术特性
- 异步处理：基于asyncio的异步图像生成
- 重试机制：自动重试失败的映像下载
- 参数验证：完成输入参数验证
- 模块化设计：核心功能与MCP服务分离
- 类型注解：完整的类型提示支持
常见问题解答
Q： 如何获取API密钥？
A： 访问火山引擎控制台，在API管理中创建一个新的API密钥。
Q： 在哪里可以找到型号ID？
A： 在Volcano引擎控制台中创建推理端点后，您可以在端点详细信息中找到ID。
Q： 支持哪些图像格式？
A： 当前生成的图像以JPG格式保存。
Q： 如何自定义图像保存路径？
A： 修改 IMAGE_SAVE_DIR 环境配置中的变量。
Q： 如果一代人失败了该怎么办？
A： 检查日志文件并确认API密钥、型号ID和网络连接正常工作。
许可证
这个项目是MIT许可证下的开源项目。
贡献
欢迎提交问题和拉取请求以改进项目