Seedream MCP

🚀 MCP Doubao Seedream 4.0 - 豆包圖片生成 MCP 服務器

這是一個基於 Model Context Protocol (MCP) 的文生圖服務器，採用豆包 Seedream 4.0 模型，可直接集成到 Claude Code 中使用，為用戶提供便捷的圖片生成體驗。

🚀 快速開始

環境要求

• Python 3.11+
• uv（推薦）或 pip
• Claude Code

安裝

# 克隆項目
git clone <your-repo-url>
cd seedream_mcp

# 方法一：使用 uv（推薦）
uv sync

# 方法二：使用 pip
pip install -r requirements.txt

注意：requirements.txt 通過以下命令生成：

uv export --format requirements.txt --output-file requirements.txt

配置

ARK_API_KEY 可以從火山方舟控制檯(https://www.volcengine.com/product/ark)獲取。 設置豆包 API 密鑰環境變量：

export ARK_API_KEY="your-api-key-here"

或在 Claude Code 配置中設置：

{
  "mcpServers": {
    "mcp-doubao": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_doubao.server"],
      "cwd": "/path/to/your/seedream_mcp",
      "env": {
        "ARK_API_KEY": "your-api-key-here"
      }
    }
  }
}

測試運行

# 測試服務器
uv run python -m mcp_doubao.server

# 測試圖片生成（可選）
uv run python -c "
import asyncio
import sys
sys.path.append('src')
from mcp_doubao.tools import handle_generate_images

async def test():
    result = await handle_generate_images({
        'prompt': '一隻可愛的小貓',
        'output_dir': './test_images'
    })
    print(result[0].text)

asyncio.run(test())
"

接入 Claude Code

詳細接入步驟請查看 INTEGRATION_GUIDE.md

方法一：使用啟動腳本（推薦）

使用項目提供的啟動腳本，自動設置虛擬環境和 Python 路徑：

{
  "mcpServers": {
    "mcp-doubao": {
      "type": "stdio",
      "command": "/path/to/your/seedream_mcp/start_mcp_server.sh",
      "env": {
        "ARK_API_KEY": "your-api-key-here"
      }
    }
  }
}

方法二：使用 uv 命令

claude mcp add-json mcp-doubao '{
  "type": "stdio",
  "command": "uv",
  "args": ["run", "python", "-m", "mcp_doubao.server"],
  "cwd": "/path/to/your/seedream_mcp",
  "env": {
    "ARK_API_KEY": "your-api-key-here"
  }
}'

✨ 主要特性

• 🎨 AI 圖片生成：基於豆包 Seedream 模型的文生圖功能
• 📁 自動下載：生成的圖片自動下載到指定目錄
• 🔧 靈活配置：支持多種尺寸、水印控制、批量生成
• 🚀 即插即用：通過 MCP 協議無縫集成到 Claude Code
• 💾 本地存儲：圖片保存到本地，便於後續使用

💻 使用示例

基礎用法

在 Claude Code 中直接用自然語言請求：

請生成一張櫻花飛舞的圖片

高級用法

生成3張不同風格的山水畫，4K分辨率，保存到artwork文件夾，不要水印

工具參數

📚 詳細文檔

項目結構

seedream_mcp/
├── src/mcp_doubao/
│   ├── __init__.py          # 模塊初始化
│   ├── server.py            # MCP 服務器入口
│   ├── tools.py             # 工具定義和處理
│   ├── doubao_client.py     # 豆包 API 客戶端
│   ├── downloader.py        # 圖片下載器
│   ├── config.py            # 配置常量
│   └── types.py             # 數據類型定義
├── start_mcp_server.sh      # Claude Code 啟動腳本（推薦使用）
├── scripts/
│   └── run_stdio.sh         # 備用啟動腳本
├── examples/
│   └── prompts.txt          # 示例提示詞
├── tests/                   # 測試文件
├── .venv/                   # Python 虛擬環境
├── pyproject.toml          # 項目配置
├── README.md               # 項目說明
└── INTEGRATION_GUIDE.md    # 接入指南

技術實現

MCP 協議

基於 Model Context Protocol 1.14.1+ 實現，提供標準化的工具接口。

API 集成

• SDK：volcengine-python-sdk[ark] 4.0.21+
• 模型：doubao-seedream-4-0-250828
• 端點：https://ark.cn-beijing.volces.com/api/v3

圖片下載

• HTTP 客戶端：httpx 0.28.1+
• 文件命名：image_001.jpeg, image_002.jpeg...（自動避免覆蓋）
• 格式支持：JPEG, PNG, WebP 等
• 防覆蓋：如果文件已存在，自動添加數字後綴

開發說明

啟動腳本功能

start_mcp_server.sh 腳本的特性：

• 自動環境設置：自動使用項目的 .venv 虛擬環境
• 路徑配置：自動設置 PYTHONPATH 到項目的 src 目錄
• 工作目錄：自動切換到項目根目錄
• 環境變量：可通過 Claude Code 配置傳入 ARK_API_KEY

本地開發

# 使用啟動腳本（推薦）
./start_mcp_server.sh

# 或使用 uv 命令
uv run python -m mcp_doubao.server

# 運行測試
uv run python -m pytest tests/

# 代碼格式化
uv run ruff format src/

# 更新 requirements.txt（添加新依賴後）
uv export --format requirements.txt --output-file requirements.txt

擴展功能

現有架構支持輕鬆擴展：

• 添加新的圖片參數（引導參數、種子等）
• 支持圖生圖功能
• 增加數據庫記錄
• 添加配額管理

故障排除

常見問題

1. 導入錯誤：確保所有依賴已正確安裝
2. API 錯誤：檢查 ARK_API_KEY 環境變量是否正確設置
3. 權限錯誤：確保輸出目錄有寫入權限
4. 圖片覆蓋：系統會自動避免覆蓋現有圖片，生成唯一文件名

調試模式

# 啟用詳細日誌
PYTHONPATH=src uv run python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
# ... 你的測試代碼
"

依賴項

核心依賴：

• mcp>=1.14.1 - Model Context Protocol
• volcengine-python-sdk[ark]>=4.0.21 - 豆包 API SDK
• httpx>=0.28.1 - HTTP 客戶端

🔧 技術細節

本項目基於 Model Context Protocol 1.14.1+ 實現了標準化的工具接口，通過 volcengine-python-sdk[ark] 4.0.21+ 與豆包 API 進行交互。在圖片下載方面，使用了 httpx 0.28.1+ 作為 HTTP 客戶端，能夠自動避免文件覆蓋，支持多種圖片格式。項目的啟動腳本 start_mcp_server.sh 可以自動設置虛擬環境和 Python 路徑，方便開發和使用。同時，項目的架構設計支持輕鬆擴展新功能，如添加圖片參數、支持圖生圖等。

📄 許可證

本項目基於 MIT 許可證開源。

貢獻

歡迎提交 Issue 和 Pull Request！

更新日誌

v0.1.0 (2024-09-23)

• ✨ 初始版本發佈
• 🎨 支持基礎圖片生成功能
• 📁 自動圖片下載
• 🔧 MCP 協議集成
• 💾 本地文件存儲