Seedream 4.0 MCP Server

# Seedream 4.0 MCP 工具 (增强版)     基于火山引擎 Seedream 4.0 API 的 MCP（Model Context Protocol）工具集，提供文生图、图生图、多图融合和组图生成等功能。 > **致谢**: 本项目基于 [tengmmvp/Seedream_MCP](https://github.com/tengmmvp/Seedream_MCP) 进行增强开发，感谢原作者的贡献！ > > **增强功能**: > - ✨ 七牛云自动上传和公网访问 > - 🎨 提示词模板系统 (8个预设模板) > - 📸 Raycast AI Markdown 图片渲染支持 > - 💾 优化的图片保存和管理 ## 功能特性 - 🎨 **文生图**：根据文本描述生成高质量图像 - 🖼️ **图生图**：基于参考图像和文本指令生成新图像 - 🎭 **多图融合**：融合多张参考图的特征生成新图像 - 📚 **组图生成**：生成一组内容关联的图像序列 - 💾 **自动保存**：自动下载并保存生成的图片到本地，解决 URL 过期问题 - ☁️ **七牛云上传**：可选的七牛云存储集成，自动上传图片并生成公网可访问的 URL - 📝 **Markdown 支持**：自动生成图片的 Markdown 引用格式（支持七牛云 URL 和本地路径） - 🔧 **完整的 MCP 协议支持**：符合 MCP 标准，可与支持 MCP 的客户端无缝集成 - 🖼️ **直接图片显示**：支持 MCP ImageContent 类型，可在客户端中直接预览图片 ## 安装要求 - Python 3.8+ - 火山引擎 Seedream 4.0 API 密钥 ## 安装方法 ### 1. 克隆项目 ```bash git clone <repository-url> cd Seedream_MCP ``` ### 2. 安装依赖 ```bash pip install -e . ``` ### 3. 配置环境变量 创建 `.env` 文件： ```bash # 必需配置 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 图片链接。详见 [七牛云集成文档](docs/QINIU_UPLOAD.md)。 ### 4. 配置 MCP 客户端 在你的 MCP 客户端配置文件中添加以下配置: **Raycast AI / Claude Desktop / Cline 等:** ```json { "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 客户端 ## 快速开始 ### 在 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 服务器运行 ```bash python -m seedream_mcp.server ``` ### 在代码中使用 ```python 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()) ``` ## 功能特性详解 ### 🎨 提示词模板系统 内置 8 个专业提示词模板,只需说出模板名称 + 关键词即可生成对应风格的图片: - **潮流派对**: 运营活动风格艺术字体 - **公众号封面**: 自动使用 21:9 比例,适合公众号配图 - **国潮风格**: 中国传统元素与现代设计结合 - **小清新**: 文艺清新风格 - **赛博朋克**: 科技未来风格 - **新年喜庆**: 节日庆典风格 - **商务简约**: 专业商务场景 - **水彩插画**: 手绘插画风格 ### ☁️ 七牛云自动上传 配置七牛云后,生成的图片会自动上传到七牛云存储: - ✅ 生成公网可访问的永久链接 - ✅ 自动生成 Markdown 图片格式 - ✅ 支持 Raycast AI 直接渲染图片 - ✅ 本地和云端双重保存 ### 💾 智能图片管理 - **自动保存**: 图片自动下载到本地,避免 URL 过期 - **按日期分类**: 自动按年/月创建文件夹 - **自动清理**: 可配置自动清理过期图片 - **并发下载**: 支持多图并发下载,提高效率 ## 工具说明 ### 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` (可选): 自定义文件名前缀 **示例：** ```json { "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` (可选): 自定义文件名前缀 **示例：** ```json { "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` (可选): 自定义文件名前缀 **示例：** ```json { "prompt": "科幻城市景观，未来主义风格", "max_images": 4, "size": "2K", "auto_save": true, "custom_name": "sci_fi_city" } ``` ## 配置选项 | 环境变量 | 描述 | 默认值 | 必需 | | ------------------------------------- | -------------------- | ------------------------------------------ | ---- | | `ARK_API_KEY` | 火山引擎 API 密钥 | - | ✅ | | `ARK_BASE_URL` | API 基础 URL | <https://ark.cn-beijing.volces.com/api/v3> | ❌ | | `SEEDREAM_MODEL_ID` | 模型 ID | doubao-seedream-4-0-250828 | ❌ | | `SEEDREAM_DEFAULT_SIZE` | 默认图像尺寸 | 2K | ❌ | | `SEEDREAM_DEFAULT_WATERMARK` | 默认水印设置 | true | ❌ | | `SEEDREAM_TIMEOUT` | 请求超时时间（秒） | 60 | ❌ | | `SEEDREAM_API_TIMEOUT` | API 超时时间（秒） | 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 | ❌ | ## 自动保存功能 自动保存功能解决了生成图片 URL 在 24 小时后过期的问题，提供永久可用的本地图片存储。 ### 核心特性 - **自动下载**：生成图片后自动下载到本地指定目录 - **智能命名**：使用时间戳 + 内容哈希 + 尺寸信息的命名规则 - **目录管理**：按工具类型和日期自动分类存储 - **Markdown 支持**：自动生成本地图片的 Markdown 引用格式 - **错误恢复**：下载失败时提供原始 URL 作为备选 - **并发下载**：支持批量图片的并发下载处理 ### 使用示例 ```python # 启用自动保存的文生图 result = await client.text_to_image( prompt="美丽的风景画", auto_save=True, custom_name="landscape" ) # 返回结果包含： # - image_url: 原始图片URL # - local_path: 本地保存路径 # - markdown: Markdown引用格式 # - save_result: 保存操作的详细信息 ``` ### 文件组织结构 ```markdown 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**: 自动清理超过指定天数的旧文件 ## 错误处理 工具提供完整的错误处理机制： - **参数验证错误**：检查必需参数和参数格式 - **API 调用错误**：处理网络错误、超时等问题 - **认证错误**：API 密钥无效或过期 - **配额错误**：API 调用次数超限 - **服务器错误**：火山引擎服务异常 ## 日志记录 工具支持详细的日志记录： - 函数调用日志 - API 请求和响应日志 - 错误和异常日志 - 性能监控日志 日志级别可通过 `LOG_LEVEL` 环境变量配置。 ## 开发和测试 ### 运行测试 ```bash # 运行集成测试 python tests/test_mcp_integration.py # 运行验证脚本 python verify_installation.py ``` ### 项目结构 ```text 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 # 说明文档 ``` ## 常见问题 ### Q: 图片在 Raycast AI 中不显示? **A:** 确保: 1. 配置了七牛云 (图片需要公网可访问的 URL) 2. 七牛云域名配置正确 3. 重启 Raycast AI ### Q: 如何关闭水印? **A:** 在 `.env` 文件中设置: ```bash 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 技术革新 国潮风格，主题：中秋节 ``` ## 贡献 欢迎贡献代码、报告问题或提出建议! ### 贡献方式 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](https://github.com/tengmmvp/Seedream_MCP) 提供的原始项目 - 感谢火山引擎提供的 Seedream 4.0 API - 感谢七牛云提供的云存储服务 ## 许可证 本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。 ## 联系方式 - **GitHub Issues**: https://github.com/joeseesun/Seedream_MCP/issues - **原项目**: https://github.com/tengmmvp/Seedream_MCP --- **⭐ 如果这个项目对你有帮助,请给个 Star!**