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文件夹，不要水印

工具参数

参数	类型	默认值	说明
`prompt`	string	必填	图片描述文本
`num_images`	int	1	生成数量 (1-3)
`size`	string	"2K"	尺寸 ("1K"/"2K"/"4K" 或具体像素如 "2048x2048")
`watermark`	bool	false	是否添加水印
`output_dir`	string	"."	保存目录
`image_paths`	array	[]	可选的参考图片路径列表 (1-10张)
`sequential_image_generation`	string	"disabled"	组图模式 ("auto"/"disabled")
`max_images`	int	3	组图模式下最大生成数量 (1-15)

项目结构

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

扩展功能

现有架构支持轻松扩展：

添加新的图片参数（引导参数、种子等）
支持图生图功能
增加数据库记录
添加配额管理

故障排除

常见问题

导入错误：确保所有依赖已正确安装
API 错误：检查 ARK_API_KEY 环境变量是否正确设置
权限错误：确保输出目录有写入权限
图片覆盖：系统会自动避免覆盖现有图片，生成唯一文件名

调试模式

# 启用详细日志 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 协议集成
💾 本地文件存储

MCP Doubao Seedream 4.0