Seedream MCP

🚀 Seedream 4.0 MCP 工具 (增強版)

基於火山引擎 Seedream 4.0 API 的 MCP（Model Context Protocol）工具集，提供文生圖、圖生圖、多圖融合和組圖生成等功能，解決了圖片 URL 過期問題，還能自動上傳到七牛雲實現公網訪問。

🚀 快速開始

在 MCP 客戶端中使用 (推薦)

配置好 MCP 客戶端後，你可以直接用自然語言對話生成圖片。

示例 1: 基礎文生圖

你說:

幫我生成一張圖片：一隻可愛的小恐龍，友好的表情，卡通風格

AI 回覆:

✅ 圖片生成成功！

• 提示詞: 一隻可愛的小恐龍，友好的表情，卡通風格
• 尺寸: 2K
• 七牛雲鏈接: https://newimg.t5t6.com/seedream/...
• 本地保存: seedream_images/2025-11-18/text_to_image/...

示例 2: 使用提示詞模板

你說:

潮流派對，關鍵詞：可口可樂

AI 回覆:

✅ 圖片生成成功！

• 提示詞: 中文"可口可樂",潮流派對風格藝術字體...
• 尺寸: 2K (默認 16:9)
• 七牛雲鏈接: https://newimg.t5t6.com/seedream/...

示例 3: 公眾號封面

你說:

公眾號封面，主題：AI 技術革新

AI 回覆:

✅ 圖片生成成功！

• 提示詞: 中文"AI 技術革新",公眾號封面風格...
• 尺寸: 2K (自動使用 21:9 比例)
• 七牛雲鏈接: https://newimg.t5t6.com/seedream/...

可用的提示詞模板

直接說出模板名稱 + 關鍵詞即可：

模板名稱	使用方式	適用場景
🎨 潮流派對	"潮流派對，關鍵詞：XXX"	運營活動、藝術字體
📱 公眾號封面	"公眾號封面，主題：XXX"	公眾號配圖 (21:9)
🎭 國潮風格	"國潮風格，主題：XXX"	中國風設計
🌸 小清新	"小清新，主題：XXX"	文藝清新風格
🎮 賽博朋克	"賽博朋克，主題：XXX"	科技未來風格
🏮 新年喜慶	"新年喜慶，主題：XXX"	節日慶典
💼 商務簡約	"商務簡約，主題：XXX"	商務場景
🎨 水彩插畫	"水彩插畫，主題：XXX"	手繪插畫風格

作為 MCP 服務器運行

python -m seedream_mcp.server

在代碼中使用

import asyncio
from seedream_mcp import SeedreamClient, SeedreamConfig

async def main():
    # 加載配置
    config = SeedreamConfig.from_env()

    # 創建客戶端
    client = SeedreamClient(config)

    try:
        # 文生圖（啟用自動保存）
        result = await client.text_to_image(
            prompt="一隻可愛的小貓咪，卡通風格",
            size="2K",
            watermark=False,
            auto_save=True,
            custom_name="cute_cat"
        )
        print(f"生成的圖像URL: {result['image_url']}")
        print(f"本地保存路徑: {result['local_path']}")
        print(f"Markdown引用: {result['markdown']}")

        # 圖生圖
        result = await client.image_to_image(
            prompt="將這張圖片轉換為油畫風格",
            image="path/to/image.jpg",
            size="2K",
            auto_save=True
        )
        print(f"轉換後的圖像URL: {result['image_url']}")
        print(f"本地保存路徑: {result['local_path']}")

    finally:
        await client.close()

if __name__ == "__main__":
    asyncio.run(main())

✨ 主要特性

• 🎨 文生圖：根據文本描述生成高質量圖像。
• 🖼️ 圖生圖：基於參考圖像和文本指令生成新圖像。
• 🎭 多圖融合：融合多張參考圖的特徵生成新圖像。
• 📚 組圖生成：生成一組內容關聯的圖像序列。
• 💾 自動保存：自動下載並保存生成的圖片到本地，解決 URL 過期問題。
• ☁️ 七牛雲上傳：可選的七牛雲存儲集成，自動上傳圖片並生成公網可訪問的 URL。
• 📝 Markdown 支持：自動生成圖片的 Markdown 引用格式（支持七牛雲 URL 和本地路徑）。
• 🔧 完整的 MCP 協議支持：符合 MCP 標準，可與支持 MCP 的客戶端無縫集成。
• 🖼️ 直接圖片顯示：支持 MCP ImageContent 類型，可在客戶端中直接預覽圖片。

📦 安裝指南

1. 克隆項目

git clone <repository-url>
cd Seedream_MCP

2. 安裝依賴

pip install -e .

3. 配置環境變量

創建 .env 文件：

# 必需配置
ARK_API_KEY=your_api_key_here

# 可選配置
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
SEEDREAM_MODEL_ID=doubao-seedream-4-0-250828
SEEDREAM_DEFAULT_SIZE=2K
SEEDREAM_DEFAULT_WATERMARK=false
SEEDREAM_TIMEOUT=60
SEEDREAM_API_TIMEOUT=60
SEEDREAM_MAX_RETRIES=3
LOG_LEVEL=INFO
LOG_FILE=logs/seedream_mcp.log

# 自動保存配置
SEEDREAM_AUTO_SAVE_ENABLED=true
SEEDREAM_AUTO_SAVE_BASE_DIR=./seedream_images
SEEDREAM_AUTO_SAVE_DOWNLOAD_TIMEOUT=30
SEEDREAM_AUTO_SAVE_MAX_RETRIES=3
SEEDREAM_AUTO_SAVE_MAX_FILE_SIZE=52428800
SEEDREAM_AUTO_SAVE_MAX_CONCURRENT=5
SEEDREAM_AUTO_SAVE_DATE_FOLDER=true
SEEDREAM_AUTO_SAVE_CLEANUP_DAYS=30

# 七牛雲配置（可選，用於上傳圖片到七牛雲存儲）
QINIU_ACCESS_KEY=your_access_key
QINIU_SECRET_KEY=your_secret_key
QINIU_BUCKET_NAME=your_bucket_name
QINIU_DOMAIN=https://your-domain.com

注意: 配置七牛雲後，生成的圖片會自動上傳到七牛雲，並在返回結果中提供公網可訪問的 Markdown 圖片鏈接。詳見 七牛雲集成文檔。

4. 配置 MCP 客戶端

在你的 MCP 客戶端配置文件中添加以下配置：

Raycast AI / Claude Desktop / Cline 等:

{
  "mcpServers": {
    "seedream": {
      "command": "python",
      "args": [
        "/你的路徑/Seedream_MCP/main.py"
      ],
      "env": {
        "ARK_BASE_URL": "https://ark.cn-beijing.volces.com/api/v3"
      }
    }
  }
}

配置文件位置:

• Raycast AI: ~/Library/Application Support/com.raycast.macos/mcp.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cline (VSCode): .vscode/settings.json 或用戶設置

重要提示:

• 將 /你的路徑/Seedream_MCP/main.py 替換為你的實際項目路徑。
• 確保 Python 環境已安裝所有依賴。
• 配置完成後重啟 MCP 客戶端。

💻 使用示例

基礎用法

import asyncio
from seedream_mcp import SeedreamClient, SeedreamConfig

async def main():
    # 加載配置
    config = SeedreamConfig.from_env()

    # 創建客戶端
    client = SeedreamClient(config)

    try:
        # 文生圖（啟用自動保存）
        result = await client.text_to_image(
            prompt="一隻可愛的小貓咪，卡通風格",
            size="2K",
            watermark=False,
            auto_save=True,
            custom_name="cute_cat"
        )
        print(f"生成的圖像URL: {result['image_url']}")
        print(f"本地保存路徑: {result['local_path']}")
        print(f"Markdown引用: {result['markdown']}")

    finally:
        await client.close()

if __name__ == "__main__":
    asyncio.run(main())

高級用法

import asyncio
from seedream_mcp import SeedreamClient, SeedreamConfig

async def main():
    # 加載配置
    config = SeedreamConfig.from_env()

    # 創建客戶端
    client = SeedreamClient(config)

    try:
        # 圖生圖
        result = await client.image_to_image(
            prompt="將這張圖片轉換為油畫風格",
            image="path/to/image.jpg",
            size="2K",
            auto_save=True
        )
        print(f"轉換後的圖像URL: {result['image_url']}")
        print(f"本地保存路徑: {result['local_path']}")

    finally:
        await client.close()

if __name__ == "__main__":
    asyncio.run(main())

📚 詳細文檔

工具說明

1. seedream_text_to_image

根據文本描述生成圖像。

參數：

• prompt (必需): 文本描述，建議不超過 300 漢字或 600 英文單詞。
• size (可選): 圖像尺寸，可選值：1K、2K、4K，默認 2K。
• watermark (可選): 是否添加水印，默認 false。
• response_format (可選): 響應格式，可選值：image、url、b64_json，默認 image。
• auto_save (可選): 是否自動保存圖片到本地，默認使用全局配置。
• save_path (可選): 自定義保存路徑，不指定則使用默認路徑。
• custom_name (可選): 自定義文件名前綴。

自然語言示例：

幫我生成一張圖片：一隻可愛的小貓咪，卡通風格

或使用提示詞模板：

潮流派對，關鍵詞：可口可樂

2. seedream_image_to_image

基於參考圖像和文本指令生成新圖像。

參數：

• prompt (必需): 圖像編輯指令。
• image (必需): 參考圖像 URL 或本地文件路徑。
• size (可選): 輸出圖像尺寸，默認 2K。
• watermark (可選): 是否添加水印，默認 false。
• response_format (可選): 響應格式，可選值：image、url、b64_json，默認 image。
• auto_save (可選): 是否自動保存圖片到本地，默認使用全局配置。
• save_path (可選): 自定義保存路徑，不指定則使用默認路徑。
• custom_name (可選): 自定義文件名前綴。

示例：

{
  "prompt": "將這張圖片轉換為油畫風格",
  "image": "https://example.com/image.jpg",
  "size": "2K",
  "watermark": false,
  "auto_save": true,
  "custom_name": "oil_painting"
}

3. seedream_multi_image_fusion

融合多張參考圖的特徵生成新圖像。

參數：

• prompt (必需): 融合指令描述。
• images (必需): 多張參考圖像 URL 或文件路徑數組（2 - 5 張）。
• size (可選): 輸出圖像尺寸，默認 2K。
• auto_save (可選): 是否自動保存圖片到本地，默認使用全局配置。
• save_path (可選): 自定義保存路徑，不指定則使用默認路徑。
• custom_name (可選): 自定義文件名前綴。

示例：

{
  "prompt": "將這些圖片融合成一個藝術作品",
  "images": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg",
    "https://example.com/image3.jpg"
  ],
  "size": "4K",
  "auto_save": true,
  "custom_name": "fusion_art"
}

4. seedream_sequential_generation

生成一組內容關聯的圖像序列。

參數：

• prompt (必需): 組圖生成描述。
• max_images (可選): 最大圖像數量（1 - 10），默認 3。
• images (可選): 參考圖像數組。
• size (可選): 圖像尺寸，默認 2K。
• auto_save (可選): 是否自動保存圖片到本地，默認使用全局配置。
• save_path (可選): 自定義保存路徑，不指定則使用默認路徑。
• custom_name (可選): 自定義文件名前綴。

示例：

{
  "prompt": "科幻城市景觀，未來主義風格",
  "max_images": 4,
  "size": "2K",
  "auto_save": true,
  "custom_name": "sci_fi_city"
}

配置選項

屬性	詳情
模型類型	未提及
訓練數據	未提及
環境變量	描述
ARK_API_KEY	火山引擎 API 密鑰
ARK_BASE_URL	API 基礎 URL
SEEDREAM_MODEL_ID	模型 ID
SEEDREAM_DEFAULT_SIZE	默認圖像尺寸
SEEDREAM_DEFAULT_WATERMARK	默認水印設置
SEEDREAM_TIMEOUT	請求超時時間（秒）
SEEDREAM_API_TIMEOUT	API 超時時間（秒）
SEEDREAM_MAX_RETRIES	最大重試次數
LOG_LEVEL	日誌級別
LOG_FILE	日誌文件路徑
SEEDREAM_AUTO_SAVE_ENABLED	是否啟用自動保存
SEEDREAM_AUTO_SAVE_BASE_DIR	自動保存基礎目錄
SEEDREAM_AUTO_SAVE_DOWNLOAD_TIMEOUT	下載超時時間（秒）
SEEDREAM_AUTO_SAVE_MAX_RETRIES	下載最大重試次數
SEEDREAM_AUTO_SAVE_MAX_FILE_SIZE	最大文件大小（字節）
SEEDREAM_AUTO_SAVE_MAX_CONCURRENT	最大併發下載數
SEEDREAM_AUTO_SAVE_DATE_FOLDER	是否創建日期文件夾
SEEDREAM_AUTO_SAVE_CLEANUP_DAYS	自動清理天數

自動保存功能

自動保存功能解決了生成圖片 URL 在 24 小時後過期的問題，提供永久可用的本地圖片存儲。

核心特性

• 自動下載：生成圖片後自動下載到本地指定目錄。
• 智能命名：使用時間戳 + 內容哈希 + 尺寸信息的命名規則。
• 目錄管理：按工具類型和日期自動分類存儲。
• Markdown 支持：自動生成本地圖片的 Markdown 引用格式。
• 錯誤恢復：下載失敗時提供原始 URL 作為備選。
• 併發下載：支持批量圖片的併發下載處理。

使用示例

# 啟用自動保存的文生圖
result = await client.text_to_image(
    prompt="美麗的風景畫",
    auto_save=True,
    custom_name="landscape"
)

# 返回結果包含：
# - image_url: 原始圖片URL
# - local_path: 本地保存路徑
# - markdown: Markdown引用格式
# - save_result: 保存操作的詳細信息

文件組織結構

images/
├── 2024-01-15/
│ ├── text_to_image/
│ │ ├── landscape_20240115_143022_abc123_2K.png
│ │ └── portrait_20240115_143045_def456_4K.png
│ ├── image_to_image/
│ │ └── style_transfer_20240115_144001_ghi789_2K.png
│ └── multi_image_fusion/
│ └── fusion_art_20240115_145030_jkl012_4K.png
└── 2024-01-16/
└── ...

配置說明

• SEEDREAM_AUTO_SAVE_ENABLED: 全局啟用/禁用自動保存。
• SEEDREAM_AUTO_SAVE_BASE_DIR: 圖片保存的根目錄。
• SEEDREAM_AUTO_SAVE_DATE_FOLDER: 是否按日期創建子文件夾。
• SEEDREAM_AUTO_SAVE_MAX_FILE_SIZE: 限制下載的最大文件大小。
• SEEDREAM_AUTO_SAVE_MAX_CONCURRENT: 控制併發下載數量。
• SEEDREAM_AUTO_SAVE_CLEANUP_DAYS: 自動清理超過指定天數的舊文件。

🔧 技術細節

功能特性詳解

提示詞模板系統

內置 8 個專業提示詞模板，只需說出模板名稱 + 關鍵詞即可生成對應風格的圖片：

• 潮流派對：運營活動風格藝術字體。
• 公眾號封面：自動使用 21:9 比例，適合公眾號配圖。
• 國潮風格：中國傳統元素與現代設計結合。
• 小清新：文藝清新風格。
• 賽博朋克：科技未來風格。
• 新年喜慶：節日慶典風格。
• 商務簡約：專業商務場景。
• 水彩插畫：手繪插畫風格。

七牛雲自動上傳

配置七牛雲後，生成的圖片會自動上傳到七牛雲存儲：

• ✅ 生成公網可訪問的永久鏈接。
• ✅ 自動生成 Markdown 圖片格式。
• ✅ 支持 Raycast AI 直接渲染圖片。
• ✅ 本地和雲端雙重保存。

智能圖片管理

• 自動保存：圖片自動下載到本地，避免 URL 過期。
• 按日期分類：自動按年/月創建文件夾。
• 自動清理：可配置自動清理過期圖片。
• 併發下載：支持多圖併發下載，提高效率。

錯誤處理

工具提供完整的錯誤處理機制：

• 參數驗證錯誤：檢查必需參數和參數格式。
• API 調用錯誤：處理網絡錯誤、超時等問題。
• 認證錯誤：API 密鑰無效或過期。
• 配額錯誤：API 調用次數超限。
• 服務器錯誤：火山引擎服務異常。

日誌記錄

工具支持詳細的日誌記錄：

• 函數調用日誌。
• API 請求和響應日誌。
• 錯誤和異常日誌。
• 性能監控日誌。

日誌級別可通過 LOG_LEVEL 環境變量配置。

📄 許可證

本項目採用 MIT 許可證。詳見 LICENSE 文件。

常見問題

Q: 圖片在 Raycast AI 中不顯示?

A: 確保:

1. 配置了七牛雲 (圖片需要公網可訪問的 URL)。
2. 七牛雲域名配置正確。
3. 重啟 Raycast AI。

Q: 如何關閉水印?

A: 在 .env 文件中設置:

SEEDREAM_DEFAULT_WATERMARK=false

Q: 圖片保存在哪裡?

A: 默認保存在 ./seedream_images/ 目錄下，按日期和功能分類：

seedream_images/
├── 2025-11-18/
│   ├── text_to_image/
│   ├── image_to_image/
│   └── multi_image_fusion/

Q: 如何使用提示詞模板?

A: 直接說出模板名稱 + 關鍵詞即可：

潮流派對，關鍵詞：可口可樂
公眾號封面，主題：AI 技術革新
國潮風格，主題：中秋節

開發和測試

運行測試

# 運行集成測試
python tests/test_mcp_integration.py

# 運行驗證腳本
python verify_installation.py

項目結構

Seedream_MCP/
├── seedream_mcp/           # 主要代碼
│   ├── __init__.py
│   ├── client.py           # API客戶端
│   ├── config.py           # 配置管理
│   ├── server.py           # MCP服務器
│   ├── tools/              # 工具實現
│   └── utils/              # 工具函數
├── docs/                   # 文檔目錄
├── tests/                  # 測試文件
├── examples/               # 使用示例
├── verifys/                # 驗證腳本
├── .env.example           # 環境變量示例
├── main.py                # 主程序入口
├── requirements.txt       # 依賴列表
└── README.md             # 說明文檔

貢獻

歡迎貢獻代碼、報告問題或提出建議！

貢獻方式

1. Fork 本倉庫。
2. 創建你的特性分支 (git checkout -b feature/AmazingFeature)。
3. 提交你的修改 (git commit -m 'Add some AmazingFeature')。
4. 推送到分支 (git push origin feature/AmazingFeature)。
5. 開啟一個 Pull Request。

開發指南

• 遵循現有代碼風格。
• 添加必要的測試。
• 更新相關文檔。
• 確保所有測試通過。

致謝

• 感謝 tengmmvp/Seedream_MCP 提供的原始項目。
• 感謝火山引擎提供的 Seedream 4.0 API。
• 感謝七牛雲提供的雲存儲服務。

---

⭐ 如果這個項目對你有幫助，請給個 Star!