shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

seedream_mcp

基于火山引擎Seedream 4.0 API的MCP工具集，提供文生图、图生图、多图融合和组图生成功能，支持七牛云自动上传、提示词模板和图片本地保存。

article

README

🚀 Seedream 4.0 MCP 工具 (增强版)

基于火山引擎 Seedream 4.0 API 的 MCP（Model Context Protocol）工具集，提供文生图、图生图、多图融合和组图生成等功能，解决了图片 URL 过期问题，还能自动上传到七牛云实现公网访问。

🚀 快速开始

在 MCP 客户端中使用 (推荐)

配置好 MCP 客户端后，你可以直接用自然语言对话生成图片。

示例 1: 基础文生图

你说:

帮我生成一张图片：一只可爱的小恐龙，友好的表情，卡通风格

AI 回复:

示例图片1

✅ 图片生成成功！

  • 提示词: 一只可爱的小恐龙，友好的表情，卡通风格
  • 尺寸: 2K
  • 七牛云链接: https://newimg.t5t6.com/seedream/...
  • 本地保存: seedream_images/2025-11-18/text_to_image/...

示例 2: 使用提示词模板

你说:

潮流派对，关键词：可口可乐

AI 回复:

示例图片2

✅ 图片生成成功！

  • 提示词: 中文"可口可乐",潮流派对风格艺术字体...
  • 尺寸: 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 | 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 作为备选。
  • 并发下载：支持批量图片的并发下载处理。

使用示例

# 启用自动保存的文生图
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!

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client