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來改進本項目。