Doubao Image Mcp Server

内容 Python

🚀 豆包图像生成MCP服务器

这是一个基于FastMCP框架和火山引擎API的图像生成MCP服务器，支持通过豆包（doubao-seedream-3.0-t2i）模型进行高质量图像生成。

🚀 快速开始

本服务器支持在多种AI开发工具中使用，如VS Code + Cline、Cursor、Trae等。配置方法如下：

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

开发工具配置说明

VS Code + Cline：在VS Code设置中找到Cline扩展配置，将上述MCP配置添加到Cline的MCP服务器配置中。
Cursor：在Cursor设置中找到MCP配置选项，添加上述配置并重启Cursor。
Trae：将上述配置添加到Trae的MCP配置文件中，保存后重新加载配置文件。

独立启动服务器

python doubao_mcp_server.py

✨ 主要特性

🎨 高质量图像生成：基于豆包seedream - 3.0 - t2i模型，支持2K分辨率。
🌐 双语支持：提示词支持中文和英文描述。
📐 多分辨率支持：支持从512x512到2048x2048的各种分辨率。
🎯 精确控制：支持种子、引导比例、水印等参数控制。
📁 本地存储：自动下载并将生成的图像保存到指定目录。
🔧 MCP协议：完全兼容MCP协议，可与支持MCP的AI助手集成。
📊 详细日志记录：完整的日志记录和错误处理。

📦 安装指南

克隆项目

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

安装方法

方法一：使用uvx直接执行（推荐）

# 从PyPI直接安装并运行
uvx doubao-image-mcp-server

方法二：使用uv安装到项目

# 安装到当前项目
uv add doubao_image_mcp_server

方法三：开发者安装

# 克隆仓库后，在项目根目录执行
uv sync
# 或者使用pip
pip install -e .

方法四：传统pip安装

pip install doubao_image_mcp_server

配置环境变量

本项目不使用.env文件，所有配置通过MCP JSON配置文件中的env字段传递。

环境变量配置示例

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

环境变量详细说明

属性	详情
BASE_URL（API基础地址）	目的：豆包（火山引擎）平台的API基础地址；默认值：`https://ark.cn-beijing.volces.com/api/v3`；说明：这是火山引擎北京区域的API地址，一般无需修改；示例：`"BASE_URL": "https://ark.cn-beijing.volces.com/api/v3"`
DOUBAO_API_KEY（API密钥）	目的：用于身份验证的API密钥；获取方式：在火山引擎控制台创建并获取；格式：通常为UUID格式的字符串；注意：请妥善保管你的API密钥，不要泄露给他人
API_MODEL_ID（模型端点ID）	目的：指定要使用的图像生成模型的推理端点ID；获取方式：在火山引擎控制台创建推理端点后获得；格式：以"ep-"开头的字符串；示例：`"API_MODEL_ID": "ep-20250528154802-c4np4"`；说明：每个推理端点都有一个唯一的ID来标识特定的模型实例
IMAGE_SAVE_DIR（图像保存目录）	目的：指定生成的图像保存的本地目录路径；路径格式：支持相对路径和绝对路径；绝对路径示例：`"IMAGE_SAVE_DIR": "C:/images"`；说明：如果目录不存在，程序将自动创建

获取API密钥和模型ID

注册火山引擎平台

使用以下URL登录火山平台并注册，你可以在右上角选择语言（中文或英文）：

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

登录火山引擎控制台

注册后，访问火山引擎控制台：

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

激活图像生成模型“豆包 - Seedream - 3.0 - t2i”

进入系统管理 → 激活管理界面。
选择视觉大模型。
找到豆包 - Seedream - 3.0 - t2i模型。
点击右侧的**“激活服务”**按钮激活服务。访问链接：

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

创建推理端点

在控制台中，点击在线推理 → 创建推理端点。
输入以下信息：
- 端点名称：为你的端点命名。
- 端点描述：添加描述信息。
- 模型选择：选择你刚刚激活的豆包 - Seedream - 3.0 - t2i模型。
点击创建按钮创建端点。
创建后，你可以在概览界面看到对应的Model_id（格式如：ep - m - 20250528154647 - cx5fg）。

创建API密钥

在控制台右侧选择API密钥管理。
点击创建API密钥。
生成并保存你的API密钥（请妥善保管，不要泄露）。

配置信息获取完成

完成上述步骤后，你将获得以下配置信息：

BASE_URL：https://ark.cn-beijing.volces.com/api/v3（固定值）
DOUBAO_API_KEY：你刚刚创建的API密钥
API_MODEL_ID：推理端点的Model_id（如：ep - m - 20250528154647 - cx5fg）
IMAGE_SAVE_DIR：图像保存目录路径

💻 使用示例

基础用法

在开发工具中配置MCP服务器后，你可以直接与AI助手对话来生成图像。

在Cursor中的使用示例

进入Agent模式。
首先让Cursor了解图像生成工具：“请了解可用的图像生成工具”。
然后直接进行图像生成请求：“请帮我生成一张日落海边风景图像”。

在其他开发工具中的使用

直接向AI助手描述你想要生成的图像。
AI助手将自动调用豆包图像生成工具。
生成的图像将保存到你配置的目录中。

高级用法

MCP工具调用

本服务器提供以下MCP工具：

`doubao_generate_image`

这是图像生成的主要工具。参数：

prompt（必需）：图像描述文本，支持中文和英文。
size（可选）：图像分辨率，默认为"1024x1024"。
seed（可选）：随机种子，如果未指定，将自动生成一个随机数，默认为 - 1。
guidance_scale（可选）：引导比例1.0 - 10.0，默认为8.0。
watermark（可选）：是否添加水印，默认为true。
file_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"
}
}

`resolutions`

获取所有可用图像分辨率的列表。

`image_generation_prompt`

提供图像生成的提示模板，包括所有参数描述和使用示例。

📚 详细文档

项目结构

doubao-image-mcp-server/
├── doubao_mcp_server.py    # 主MCP服务器
├── doubao_image_gen.py     # 核心图像生成工具
├── pyproject.toml          # 项目配置和依赖管理
├── uv.lock                 # 依赖锁定文件
├── .gitignore             # Git忽略文件
├── LICENSE                # 开源许可证
├── README.md              # 英文项目文档
├── README_CN.md           # 中文项目文档
└── images/                # 文档图片目录
├── create_api_key.jpg
├── create_inference_endpoint.jpg
├── model_activation.jpg
└── volcengine_signup.jpg

🔧 技术细节

日志系统

本项目包含一个完整的日志系统：

文件日志：保存在log/目录中。
控制台日志：输出到stderr进行调试。
日志级别：DEBUG、INFO、WARNING、ERROR。

错误处理

✅ 环境变量验证
✅ 参数类型和范围检查
✅ API调用错误处理
✅ 图像下载重试机制
✅ 文件保存异常处理

技术特性

异步处理：基于asyncio的异步图像生成。
重试机制：图像下载失败时自动重试。
参数验证：完整的输入参数验证。
模块化设计：核心功能与MCP服务分离。
类型注解：完整的类型提示支持。

📄 许可证

本项目采用MIT许可证进行开源。

常见问题解答

Q：如何获取API密钥？

A：访问火山引擎控制台，在API管理中创建新的API密钥。

Q：在哪里可以找到Model ID？

A：在火山引擎控制台创建推理端点后，可以在端点详情中找到ID。

Q：支持哪些图像格式？

A：目前生成的图像以JPG格式保存。

Q：如何自定义图像保存路径？

A：修改环境配置中的IMAGE_SAVE_DIR变量。

Q：如果生成失败怎么办？

A：检查日志文件，确认API密钥、模型ID和网络连接是否正常。

贡献说明

欢迎提交Issues和Pull Requests来改进本项目。

0 条评论
分类：内容