Doubao Image MCP Server

🚀 豆包图像生成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"
}

环境变量详细说明

获取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”

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

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

创建推理端点

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

创建API密钥

1. 在控制台右侧选择API密钥管理。
2. 点击创建API密钥。
3. 生成并保存你的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中的使用示例

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

在其他开发工具中的使用

• 直接向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来改进本项目。