MCP Doubao Seedream 4.0 - 豆包图片生成 MCP 服务器

一个基于 Model Context Protocol (MCP) 的豆包 Seedream 4.0 模型的文生图服务器可以直接集成到 Claude Code 中使用

功能特性

• AI 图片生成基于豆包 Seedream 模型的文生图功能
• 自动下载生成的图片自动下载到指定目录
• 灵活配置支持多种尺寸水印控制批量生成
• 即插即用通过 MCP 协议无缝集成到 Claude Code
• 本地存储图片保存到本地便于后续使用

快速开始

1. 环境要求

• Python 3.11+
• uv (推荐) 或 pip
• Claude Code

2. 安装

# 克隆项目
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

3. 配置

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

4. 测试运行

# 测试服务器
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())
"

5. 接入 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"
  }
}'

使用方法

基本使用

在 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 客户端

许可证

本项目基于 MIT 许可证开源

贡献

欢迎提交 Issue 和 Pull Request

更新日志

v0.1.0 (2024-09-23)

• 初始版本发布
• 支持基础图片生成功能
• 自动图片下载
• MCP 协议集成
• 本地文件存储