Skip to main content
Glama
tengmmvp

Seedream 4.0 MCP

by tengmmvp
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

⚡ 快速安装

1. 前置准备

安装 uv（包含 uvx 命令）：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

在火山引擎控制台获取 API 密钥，通过环境变量 ARK_API_KEY 提供。

2. 一键启动

# 通过环境变量提供密钥（推荐）
ARK_API_KEY=your_api_key_here uvx seedream-image-mcp

# 也可显式指定模型、尺寸等运行参数
ARK_API_KEY=your_api_key_here uvx seedream-image-mcp --model doubao-seedream-5.0 --default-size 2K

uvx 自动从 PyPI 拉取最新版本并在隔离环境运行——无需 clone 仓库、无需手动创建虚拟环境、无需安装依赖。

3. 可选：Docker Compose

# 下载 docker-compose.yml
curl -O https://raw.githubusercontent.com/tengmmvp/Seedream_MCP/main/docker-compose.yml

# 可选：创建 .env（参考 .env.example）供 compose 只读挂载，替代下行环境变量前置
# 不创建 .env 时 Docker 会自动创建同名目录导致挂载异常，需先 touch .env 或删除 compose 中的该挂载

# 启动服务
ARK_API_KEY=your_api_key_here SEEDREAM_HTTP_AUTH_TOKEN=your_token_here docker compose up -d

服务以 streamable-http 传输监听容器内 8000 端口，宿主机端口由 SEEDREAM_HTTP_PORT 控制（默认 8000），MCP 端点路径为 /mcp。端口映射默认仅绑定回环地址 127.0.0.1，需从其他设备直连时把 docker-compose.yml 中的端口映射改为 0.0.0.0:${SEEDREAM_HTTP_PORT:-8000}:8000 或指定宿主机网卡地址。端口映射改为 0.0.0.0 即把服务暴露给网络，此时 SEEDREAM_HTTP_AUTH_TOKEN 会以明文 HTTP 过网传输；必须将服务置于 TLS 反向代理之后，或通过 SEEDREAM_EXTRA_CLI_ARGS 向容器提供 TLS 证书参数，禁止在无 TLS 的状态下对外暴露。客户端接入配置（以 Claude Desktop 为例，其他支持 streamable-http 的客户端同理）：

{
  "mcpServers": {
    "seedream-image-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

<token> 为占位符，须与服务端环境变量 SEEDREAM_HTTP_AUTH_TOKEN 一致；若经 TLS 反向代理或容器内 TLS 暴露，url 改用 https:// 形态（如 https://mcp.example.com/mcp）。静态令牌鉴权不提供 OAuth 受保护资源元数据发现，标准 OAuth 客户端需手动配置凭据。

Related MCP server: Seedream 4.0 MCP Server

🔧 客户端配置

推荐通过 env 注入 ARK_API_KEY，避免把密钥写进 args（命令行参数会出现在进程列表中，存在泄露风险）。

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "seedream-image-mcp": {
      "command": "uvx",
      "args": ["seedream-image-mcp"],
      "env": { "ARK_API_KEY": "your_api_key_here" }
    }
  }
}

Claude Code（命令行一键注册）

claude mcp add seedream-image-mcp --env ARK_API_KEY=your_api_key_here -- uvx seedream-image-mcp

Cursor

在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "seedream-image-mcp": {
      "command": "uvx",
      "args": ["seedream-image-mcp"],
      "env": { "ARK_API_KEY": "your_api_key_here" }
    }
  }
}

Cline / 其他 stdio 客户端

通用配置（command + args + env 字段同上）。Cline 编辑 cline_mcp_settings.json：

{
  "mcpServers": {
    "seedream-image-mcp": {
      "command": "uvx",
      "args": ["seedream-image-mcp"],
      "env": { "ARK_API_KEY": "your_api_key_here" }
    }
  }
}

需要指定模型/尺寸时，追加到 args，例如 ["seedream-image-mcp", "--model", "doubao-seedream-5.0"]。

配置后重启对应客户端即可使用。

🖥️ Web 操作台

不使用 MCP 客户端的用户也可以直接通过网页使用：以 --web 旗标（或环境变量 SEEDREAM_WEB_ENABLED=true）启动 streamable-http 传输后，浏览器访问 http://127.0.0.1:8000/web 即可打开操作台，覆盖文生图、图生图、多图融合、组图生成与历史图库。默认关闭，stdio 传输与未开启时不暴露任何 Web 端点。

ARK_API_KEY=your_api_key_here uvx seedream-image-mcp --transport streamable-http --web --auth-token your_token_here

鉴权方式：网页本身无需令牌即可打开；网页的功能接口在部署配置了令牌时需要验证——首次使用在页面中输入一次即可，令牌只保存在浏览器本地，不会出现在网址中。仅本机使用且未配置令牌时，全程无需输入任何东西，接口也只接受来自本页面与本机程序的请求。

⚙️ 启动参数

# 认证与配置来源
--api-key TEXT                                     # API 密钥（可选，推荐用环境变量 ARK_API_KEY）
--config-file TEXT                                 # 自定义 .env 配置文件路径

# 模型与生成
--model [doubao-seedream-5.0-pro|doubao-seedream-5.0|doubao-seedream-5.0-lite|doubao-seedream-4.5|doubao-seedream-4.0]
                                                 # 模型选择 (默认: doubao-seedream-5.0)
--default-size [1K|1.5K|2K|3K|4K|<宽>x<高>]        # 图像尺寸 (默认: 2K，需与所选模型兼容)
--watermark                                        # 启用水印
--no-watermark                                     # 关闭水印

# 连接与传输
--base-url TEXT                                    # API 基础 URL（默认按配置或内置默认值；须 https，http 需设 SEEDREAM_ALLOW_HTTP_BASE_URL=true 豁免）
--transport [stdio|streamable-http]                # MCP 传输方式 (默认: stdio)
--host TEXT                                        # streamable-http 监听地址 (默认: 127.0.0.1；绑定非回环地址必须配置 --auth-token 与 TLS（或 --insecure-allow-non-tls 豁免），否则拒绝启动)
--port INTEGER                                     # streamable-http 监听端口 (默认: 8000)
--stateless                                        # streamable-http 无状态模式，仅作用于带握手会话的旧规范修订客户端链路，代价是失去反向通道 (默认关闭)
--web                                              # 开启 Web 操作台，浏览器访问 /web 直接使用 (默认关闭，仅 streamable-http 生效)
--no-web                                           # 关闭 Web 操作台，覆盖 SEEDREAM_WEB_ENABLED 的开启设置

# 安全
--auth-token TEXT                                  # Bearer 鉴权令牌（非回环绑定必须配置，也可用 SEEDREAM_HTTP_AUTH_TOKEN）
--ssl-certfile TEXT                                # TLS 证书文件（非回环绑定必须配置，防令牌明文传输，启用后最低协议版本 TLS 1.2；受信反向代理终结 TLS 时可用 --insecure-allow-non-tls 豁免）
--ssl-keyfile TEXT                                 # TLS 私钥文件，与 --ssl-certfile 配合
--insecure-allow-non-tls                           # 显式允许非回环明文运行（仅受信反向代理终结 TLS 场景）

# 日志
--log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]    # 日志级别

安全提示：localhost 不被视为回环地址（其解析依赖 hosts/DNS，可能被污染指向非回环），绑定它同样要求配置 Bearer 鉴权令牌与 TLS，未配置则服务拒绝启动；如需回环免鉴权语义，请改绑 127.0.0.1 或 ::1。非回环绑定同样必须配置 Bearer 令牌与 TLS。生产与容器部署应通过环境变量（ARK_API_KEY / SEEDREAM_HTTP_AUTH_TOKEN）传递密钥，而非 CLI --api-key / --auth-token（命令行参数会暴露在进程列表与 shell 历史记录中）；多用户主机上 streamable-http 即使绑定回环地址，也建议配置鉴权令牌。Web 操作台不改变上述传输层安全要求：开启后新增的 API 面全部强制令牌，免鉴权的仅限无数据的静态页面骨架。

使用示例

# 基础使用
ARK_API_KEY=your_key uvx seedream-image-mcp

# 使用自定义配置文件
ARK_API_KEY=your_key uvx seedream-image-mcp --config-file ./my-config.env

# 切换其他模型（如 4.0 / 4.5）并指定尺寸与调试模式
ARK_API_KEY=your_key uvx seedream-image-mcp --model doubao-seedream-4.5 --default-size 4K --log-level DEBUG

# 高精度生图（5.0 Pro；注意：不支持组图 / 联网搜索 / 流式输出，尺寸仅 1K/1.5K/2K）
ARK_API_KEY=your_key uvx seedream-image-mcp --model doubao-seedream-5.0-pro

📐 模型能力差异

各模型支持的能力与参数范围不同，选择模型时请留意：

能力 / 参数

5.0 Pro

5.0 / 5.0 Lite

4.5

4.0

文生图 / 图生图 / 多图生图

✅

✅

✅

✅

组图生成

❌

✅

✅

✅

联网搜索

❌

✅

❌

❌

流式输出

❌

✅

✅

✅

输出格式（png/jpeg）

✅

✅

❌

❌

图层拆分

✅

❌

❌

❌

透明背景

✅

❌

❌

❌

分辨率档位

1K / 1.5K / 2K

2K / 3K / 4K

2K / 4K

1K / 2K / 4K

自定义尺寸倍数

16 的倍数

不限制

不限制

不限制

MCP 默认尺寸

2048x2048

2048x2048

2048x2048

2048x2048

参考图上限

10 张

14 张

14 张

14 张

MCP 默认尺寸：表中“MCP 默认尺寸”行为 MCP 统一配置 default_size=2K（对应 2048x2048）的运行时解析值，与各模型原生默认无关。

提示：默认模型为 doubao-seedream-5.0（与 5.0 Lite 等价），开箱即用全部能力。切换到 doubao-seedream-5.0-pro 后，组图、联网搜索、流式输出不可用，尺寸仅支持 1K/1.5K/2K（默认 2048x2048），多图生图参考图上限降为 10 张，另独享图层拆分与透明背景能力。

🛠️ 可用工具

根据文本提示词生成图像。该工具调用外部计费 API、在本地产出文件，非只读。

参数：

  • prompt (必需) - 图像生成的文本提示词，建议不超过 300 个汉字或 600 个英文单词

  • optimize_prompt_options (可选) - 提示词优化选项，支持 mode: "standard" 或 "fast"，fast 仅 5.0 Pro / 4.0 支持

  • size (可选) - 图像尺寸：1K、1.5K、2K、3K、4K 或 <宽>x<高> 像素值，默认使用配置文件值，需与所选模型兼容

  • watermark (可选) - 是否添加水印，默认使用配置文件值（默认 false）

  • response_format (可选) - 响应格式：url或b64_json，默认url

  • output_format (可选) - 输出文件格式，仅 5.0 系列（Pro/标准/Lite）支持 jpeg 或 png，默认不指定，由 API 按模型默认处理

  • stream (可选) - 是否启用流式输出，默认false（5.0 Pro 不支持）

  • tools (可选) - 模型工具配置，仅 doubao-seedream-5.0 / 5.0-lite 系列支持联网搜索，例如 [{"type":"web_search"}]

  • request_count (可选) - 同一提示并行发起的独立生成次数，每次各产出一张图，范围 1-10，默认 1

  • parallelism (可选) - 并行度上限，范围 1-10，默认 min(request_count, 10)，一般无需手动指定

  • auto_save (可选) - 是否自动保存到本地，默认使用全局配置（默认 true）

  • save_path (可选) - 自定义保存目录路径

  • custom_name (可选) - 自定义文件名前缀

调用示例：

{
  "name": "text_to_image",
  "arguments": {
    "prompt": "水彩风格的江南水乡，清晨薄雾"
  }
}

根据输入图像和文本提示生成新图像。该工具调用外部计费 API、在本地产出文件，非只读。

参数：

  • prompt (可选) - 图像修改要求或风格转换指令，建议不超过 300 个汉字或 600 个英文单词；仅图层拆分场景可缺省，由模型自动识别拆分意图

  • optimize_prompt_options (可选) - 提示词优化选项，支持 mode: "standard" 或 "fast"，fast 仅 5.0 Pro / 4.0 支持

  • image (必需) - 输入图像，支持图像 URL、本地文件路径或 Base64 图片数据

  • layer_decomposition (可选) - 是否开启图层拆分，仅 5.0 Pro 支持；开启后将单张输入图拆解为 1 张底图与最多 16 个带透明通道的 PNG 图层，图层条目额外返回 z_index、name、description、bounding_box 字段；output_format 仅控制底图格式，图层始终为 PNG

  • background (可选) - 透明通道，transparent 生成透明背景图（需输入单张带透明通道的图片，与 output_format=jpeg 互斥）或 opaque 生成常规图，仅 5.0 Pro 支持

  • size (可选) - 图像尺寸：1K、1.5K、2K、3K、4K 或 <宽>x<高> 像素值，默认使用配置文件值，需与所选模型兼容；图层拆分场景仅支持档位与 auto（按输入图自适应，未指定尺寸时的默认值）

  • watermark (可选) - 是否添加水印，默认使用配置文件值（默认 false）

  • response_format (可选) - 响应格式：url或b64_json，默认url

  • output_format (可选) - 输出文件格式，仅 5.0 系列（Pro/标准/Lite）支持 jpeg 或 png，默认不指定，由 API 按模型默认处理

  • stream (可选) - 是否启用流式输出，默认false（5.0 Pro 不支持）

  • tools (可选) - 模型工具配置，仅 doubao-seedream-5.0 / 5.0-lite 系列支持联网搜索，例如 [{"type":"web_search"}]

  • request_count (可选) - 同一提示并行发起的独立生成次数，每次各产出一张图，范围 1-10，默认 1

  • parallelism (可选) - 并行度上限，范围 1-10，默认 min(request_count, 10)，一般无需手动指定

  • auto_save (可选) - 是否自动保存到本地，默认使用全局配置（默认 true）

  • save_path (可选) - 自定义保存目录路径

  • custom_name (可选) - 自定义文件名前缀

调用示例：

{
  "name": "image_to_image",
  "arguments": {
    "prompt": "把这张人像照片转换为吉卜力动画风格",
    "image": ".seedream/images/2026-08-15/image_to_image/portrait.jpeg"
  }
}

将多张图像融合生成新图像。该工具调用外部计费 API、在本地产出文件，非只读。

参数：

  • prompt (必需) - 图像融合要求或风格指令，建议不超过 300 个汉字或 600 个英文单词

  • optimize_prompt_options (可选) - 提示词优化选项，支持 mode: "standard" 或 "fast"，fast 仅 5.0 Pro / 4.0 支持

  • image (必需) - 输入图像（2-14 张；5.0 Pro 最多 10 张），每张支持图像 URL、本地文件路径或 Base64 图片数据

  • size (可选) - 图像尺寸：1K、1.5K、2K、3K、4K 或 <宽>x<高> 像素值，默认使用配置文件值，需与所选模型兼容

  • watermark (可选) - 是否添加水印，默认使用配置文件值（默认 false）

  • response_format (可选) - 响应格式：url或b64_json，默认url

  • output_format (可选) - 输出文件格式，仅 5.0 系列（Pro/标准/Lite）支持 jpeg 或 png，默认不指定，由 API 按模型默认处理

  • stream (可选) - 是否启用流式输出，默认false（5.0 Pro 不支持）

  • tools (可选) - 模型工具配置，仅 doubao-seedream-5.0 / 5.0-lite 系列支持联网搜索，例如 [{"type":"web_search"}]

  • request_count (可选) - 同一提示并行发起的独立生成次数，每次各产出一张图，范围 1-10，默认 1

  • parallelism (可选) - 并行度上限，范围 1-10，默认 min(request_count, 10)，一般无需手动指定

  • auto_save (可选) - 是否自动保存到本地，默认使用全局配置（默认 true）

  • save_path (可选) - 自定义保存目录路径

  • custom_name (可选) - 自定义文件名前缀

调用示例：

{
  "name": "multi_image_fusion",
  "arguments": {
    "prompt": "把两张人像融合为一张双人合影，影棚灯光",
    "image": [
      ".seedream/images/2026-08-15/multi_image_fusion/person_a.jpeg",
      ".seedream/images/2026-08-15/multi_image_fusion/person_b.jpeg"
    ]
  }
}

连续生成多张图像，支持文生组图、单图生组图、多图生组图（仅 doubao-seedream-5.0 系列（5.0/5.0-lite）/4.5/4.0 支持；5.0 Pro 不支持组图）。该工具调用外部计费 API、在本地产出文件，非只读。

参数：

  • prompt (必需) - 图像生成的文本提示词，应明确指明生成数量和内容，建议不超过 300 个汉字或 600 个英文单词

  • optimize_prompt_options (可选) - 提示词优化选项，支持 mode: "standard" 或 "fast"，fast 仅 5.0 Pro / 4.0 支持

  • image (可选) - 参考图像（最多 14 张，且参考图数量与 max_images 之和不超过 15），每张支持图像 URL、本地文件路径或 Base64 图片数据

  • size (可选) - 图像尺寸：1K、1.5K、2K、3K、4K 或 <宽>x<高> 像素值，默认使用配置文件值，需与所选模型兼容

  • watermark (可选) - 是否添加水印，默认使用配置文件值（默认 false）

  • max_images (可选) - 最大生成图像数量，范围 1-15，默认 15；提供参考图时默认自动扣减为 15 减参考图数量

  • response_format (可选) - 响应格式：url或b64_json，默认url

  • output_format (可选) - 输出文件格式，仅 5.0 系列（Pro/标准/Lite）支持 jpeg 或 png，默认不指定，由 API 按模型默认处理

  • stream (可选) - 是否启用流式输出，默认false

  • tools (可选) - 模型工具配置，仅 doubao-seedream-5.0 / 5.0-lite 系列支持联网搜索，例如 [{"type":"web_search"}]

  • request_count (可选) - 同一提示并行发起的独立生成次数，每次各产出一组图片，组内图片数量由模型按提示词决定，最多 max_images 张，范围 1-10，默认 1

  • parallelism (可选) - 并行度上限，范围 1-10，默认 min(request_count, 10)，一般无需手动指定

  • auto_save (可选) - 是否自动保存到本地，默认使用全局配置（默认 true）

  • save_path (可选) - 自定义保存目录路径

  • custom_name (可选) - 自定义文件名前缀

调用示例：

{
  "name": "sequential_generation",
  "arguments": {
    "prompt": "四格漫画：一只柴犬的一天，起床、吃饭、散步、睡觉"
  }
}

浏览工作区中的图片文件，获取文件路径用于图像生成。该工具只读、幂等、不访问网络。

参数：

  • directory (可选) - 要浏览的目录路径，默认浏览工作区根目录（MCP Roots 授权的首个根；无 Roots 时回退 SEEDREAM_WORKSPACE_ROOT 配置的本地工作区根，均未设置时为进程当前工作目录）

  • recursive (可选) - 是否递归搜索子目录，默认true

  • max_depth (可选) - 最大搜索深度，范围 1-10，默认 3

  • limit (可选) - 返回的最大文件数量，范围 1-200，默认 50

  • offset (可选) - 分页偏移量（0-100000，从第几张开始返回），配合 limit 翻页，默认 0

  • format_filter (可选) - 过滤特定图片格式，如['.jpeg', '.png']

  • show_details (可选) - 是否显示详细文件信息，默认false

调用示例：

{
  "name": "browse_images",
  "arguments": {}
}

📦 可用资源

除工具外，服务端还暴露以下 MCP 资源供客户端读取运行时信息：

资源 URI

说明

seedream://workspace/roots

客户端授权的 MCP 工作区 Roots；未授权时为空，避免暴露服务器本地目录

seedream://server/info

服务器名称、版本与当前生效配置摘要（模型、默认尺寸、自动保存开关，共五项字段）

seedream://models/info

各模型别名与能力声明：支持的尺寸档位、像素范围、像素倍数、参考图上限、输出格式/工具/流式等能力，供客户端按需选择模型

skill://seedream-image-generation/SKILL.md

Agent Skill 主文件：图像生成指南入口，正文含工具速查、模型差异与参数规则

skill://seedream-image-generation/references/{+path}

Agent Skill 参考文件模板：多步工作流与故障排查，按需读取

🧠 Agent Skills

服务器随包分发 Agent Skills 开放标准技能目录，为 AI 客户端提供图像生成的完整方法论，两种方式可用：

  • 资源自动发现：客户端直接读取上表 skill:// 资源，主文件常驻资源列表，参考文件按需读取

  • 手动安装：将包内 seedream_mcp/skills/seedream-image-generation/ 整目录拷贝到客户端技能目录，例如 Claude Code 的 ~/.claude/skills/

python -c "import pathlib, shutil, seedream_mcp; src = pathlib.Path(seedream_mcp.__file__).parent / 'skills' / 'seedream-image-generation'; shutil.copytree(src, pathlib.Path.home() / '.claude' / 'skills' / 'seedream-image-generation', dirs_exist_ok=True)"

技能目录包含以下文件：

文件

内容

SKILL.md

生成指南主文件：工具速查、模型差异、提示词写法、参数规则

references/workflows.md

多步工作流：连环画端到端、图层拆分与再合成、风格一致性迭代

references/troubleshooting.md

故障排查：错误码对策、常见失败模式、输入与配额约束

🎭 风格预设

服务端内置以下 MCP 提示词模板，一键生成指定风格的文生图 prompt，可通过 subject 参数指定画面主题：

Prompt 名称

风格

默认主题

seedream_style_anime

日系动漫风格，赛璐珞上色，鲜艳饱和色彩

一个女孩站在樱花树下

seedream_style_realistic

写实摄影风格，高清细节，自然光影

城市夜景

seedream_style_watercolor

水彩画风格，柔和晕染，通透色彩

山间小屋

seedream_style_oil_painting

油画风格，厚重笔触，丰富层次

海边夕阳

❓ 常见问题

Q: uvx 命令不存在？

curl -LsSf https://astral.sh/uv/install.sh | sh

Q: 如何获取 API 密钥？ 访问 火山引擎控制台 创建密钥

Q: Docker 服务无法启动？ 确保设置了环境变量：

# Linux/macOS
export ARK_API_KEY=your_key
export SEEDREAM_HTTP_AUTH_TOKEN=your_token
docker compose up -d

# Windows
$env:ARK_API_KEY="your_key"
$env:SEEDREAM_HTTP_AUTH_TOKEN="your_token"
docker compose up -d

🧪 本地开发

# 克隆仓库
git clone https://github.com/tengmmvp/Seedream_MCP
cd Seedream_MCP

# 安装依赖（开发模式）
uv sync

# 创建 .env 文件
cp .env.example .env
# 编辑 .env 文件，添加您的 API 密钥

# 启动服务
uv run python -m seedream_mcp.server

# 或直接使用 API 密钥启动
uv run python -m seedream_mcp.server --api-key your_key

⚙️ 环境变量配置

主要配置项（详见 .env.example）：

配置优先级：MCP 客户端显式配置（命令行参数） > 运行时系统环境变量 > .env 文件 > 默认值。

.env 加载规则：

  • 使用 --config-file 时：仅加载指定文件。

  • 未指定 --config-file 时：按“项目根 .env -> 当前工作目录 .env”顺序合并，后者覆盖前者。

  • .env 的值不会注入进程环境变量，仅按上述优先级解析后写入配置对象，避免污染全局状态；系统环境变量优先于 .env 文件。

# 必需配置
ARK_API_KEY=your_api_key_here

# API 端点安全
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3   # API 基础 URL，默认火山引擎北京端点；须 https，http 会使 API Key 明文传输而被默认拒绝，仅自建可信内网端点可经 SEEDREAM_ALLOW_HTTP_BASE_URL 豁免
SEEDREAM_ALLOW_HTTP_BASE_URL=false                      # 豁免 http:// 的 ARK_BASE_URL（默认拒绝明文传输；仅自建可信内网端点设 true）

# 模型配置
SEEDREAM_MODEL_ID=doubao-seedream-5.0

# 默认值
SEEDREAM_DEFAULT_SIZE=2K
SEEDREAM_DEFAULT_WATERMARK=false

# 超时
SEEDREAM_TIMEOUT=60                         # 连接建立/写入/连接池获取超时（秒）
SEEDREAM_API_TIMEOUT=600                    # API 调用读取与总超时（秒）
SEEDREAM_MAX_RETRIES=3                      # API 调用最大重试次数（429/5xx、超时与网络错误重试，4xx 不重试）

# 日志
LOG_LEVEL=INFO                              # 日志级别（DEBUG / INFO / WARNING / ERROR / CRITICAL）
LOG_FILE=                                   # 日志文件路径（默认 .seedream/logs/seedream_mcp.log，相对进程工作目录解析）

# 自动保存
SEEDREAM_AUTO_SAVE_ENABLED=true
SEEDREAM_AUTO_SAVE_BASE_DIR=                # 图片保存根目录（默认 <工作区根>/.seedream/images，工作区根取 MCP Roots 首项或 SEEDREAM_WORKSPACE_ROOT）
SEEDREAM_AUTO_SAVE_DOWNLOAD_TIMEOUT=30      # 单张图片下载超时（秒），上限 720
SEEDREAM_AUTO_SAVE_MAX_RETRIES=3            # 下载失败最大重试次数（0 表示不重试）
SEEDREAM_AUTO_SAVE_MAX_FILE_SIZE=52428800   # 单张图片大小上限（字节，默认 50MB）；另兼作流式单事件截断阈值与响应体读取上限的推导基准
SEEDREAM_RESPONSE_BODY_LIMIT=               # 上游响应体读取总量上限（字节；不设则按 SEEDREAM_AUTO_SAVE_MAX_FILE_SIZE×20 推导，非流式/流式 JSON 与 SSE 共用）
SEEDREAM_AUTO_SAVE_MAX_CONCURRENT=5         # 最大并发下载数
SEEDREAM_AUTO_SAVE_DATE_FOLDER=true
SEEDREAM_AUTO_SAVE_CLEANUP_DAYS=30
SEEDREAM_AUTO_SAVE_FSYNC=false               # 落盘前 fsync：开启提升崩溃一致性、略降写入吞吐，默认关闭
SEEDREAM_AUTO_SAVE_MAX_TOTAL_BYTES=10737418240 # 保存目录总字节上限（默认 10GB；超限按最旧文件驱逐）
SEEDREAM_PREVIEW_ENABLED=true                 # 生成结果附带已保存图片的缩略图（对话内直接预览，依赖自动保存；默认开启）

# 工作区与传输
SEEDREAM_WORKSPACE_ROOT=                    # 本地开发时文件读写边界回退目录（MCP Roots 优先）
SEEDREAM_HTTP_AUTH_TOKEN=                   # streamable-http Bearer 鉴权令牌（非回环绑定必须配置，否则拒绝启动；另需 TLS 或 --insecure-allow-non-tls 豁免）
SEEDREAM_HTTP_MAX_BODY_SIZE=67108864        # streamable-http 请求体上限（字节，≥1MB，默认 64MB；单图 data URI 约 40MB，兼顾多图融合）
SEEDREAM_WEB_ENABLED=false                  # Web 操作台开关（--web/--no-web 覆盖；仅 streamable-http 生效，开启后浏览器可访问 /web 页面与历史图库，默认关闭）
SEEDREAM_HTTP_ALLOWED_HOSTS=                # 非回环直连部署的 Host 头允许列表，逗号分隔，支持 host:port 与尾部 :* 通配（如 mcp.example.com,mcp.example.com:*）；留空则整体关闭 SDK 内层 Host 校验，适用反向代理场景
SEEDREAM_REQUEST_STATE_KEYS=               # 多副本 HTTP 部署共享的 requestState 密钥环，逗号分隔十六进制，每键解码后不少于 32 字节；留空保持 SDK 默认进程临时密钥，单进程部署可省略；多副本部署下，按 2026-07-28 之前规范修订连接的客户端带会话，需粘性路由固定到同一实例，2026-07-28 修订的客户端无会话，任意副本均可应答

# 客户端性能
SEEDREAM_IMAGE_PREPARE_CONCURRENCY=5
SEEDREAM_PREPARE_CACHE_MAX=32
SEEDREAM_PREPARE_CACHE_MAX_BYTES=268435456    # 参考图预处理缓存累计字节上限（默认 256MB）

# 流式处理
SEEDREAM_STREAM_BUFFER_MAX_SIZE=10485760      # SSE 流式响应缓冲区前缀回收阈值（默认 10MB）
SEEDREAM_STREAM_CHUNK_SIZE=1048576            # SSE 流式响应每次读取块大小（默认 1MB）

部署注意事项

  • 保存目录归服务管理：自动保存的按天清理与总量配额会删除保存目录内所有符合图片扩展名的过期文件与空目录，不区分是否由本服务生成。请勿将 SEEDREAM_AUTO_SAVE_BASE_DIR 指向个人相册等含重要图片的目录。

  • 多租户 streamable-http 部署建议显式设置 SEEDREAM_WORKSPACE_ROOT：MCP Roots 读取失败时文件访问边界会回退到该环境变量（未设置时为进程工作目录）。

  • 未认证请求的体积限制：未携带有效令牌的 chunked 请求不读 body 即返回 401，其体积限制依赖 uvicorn 层或前置反向代理；公网暴露部署请在代理层配置请求体上限。

  • Linux 宿主挂载目录属主：容器以 uid 1000 的非 root 用户运行，Linux 宿主上 compose 挂载的 ./.seedream 目录需对该用户可写（mkdir -p .seedream && chown 1000:1000 .seedream）；Docker Desktop 不受影响。

👥 贡献者

项目维护者

重要贡献者

  • @caoergou - 通过 PR #2 贡献了 uvx 支持、Docker 容器化配置、GitHub Actions 自动化发布流程，极大简化了项目的安装与部署体验

📄 许可证

这个项目基于 MIT 许可证开源。更多信息请查看 LICENSE 文件。

Available Tools

5 tools
seedream_browse_imagesA
Read-onlyIdempotent

本地图片浏览：

浏览工作目录中的图片文件，便于用户选择参考图或查看已生成内容。

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, destructiveHint, and idempotentHint, establishing safe read-only behavior. Description adds browsing context but no additional behavioral traits beyond what annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is highly concise and front-loaded, communicating the core purpose immediately. No wasted words or redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the six parameters and no output schema, the description lacks details on what browsing returns (e.g., file list format) or how pagination works. While annotations cover safety, the description is minimal for full contextual completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover all parameters with detailed explanations (e.g., directory, recursive, format_filter). Tool description does not add parameter meaning, but schema coverage is high, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states '浏览本地图片' (browse local images) in the working directory with specific use cases (selecting reference images or viewing generated content). It effectively distinguishes from sibling generation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied (for selecting references or viewing outputs), but no explicit guidance on when to use vs. alternatives or when to avoid. Siblings are different in nature, so confusion is unlikely, but still lacks explicit direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

seedream_image_to_imageA

图文生图：

基于已有图片，结合文字指令进行图像编辑，包括图像元素增删、风格转化、材质替换、色调迁移、改变背景/视角/尺寸等。

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description indicates the tool modifies images (readOnlyHint false), but it does not elaborate on behavioral traits such as whether the original image is altered (likely a new image is generated), authentication needs, or rate limits. The description adds minimal context beyond what the annotations already imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the tool's purpose and capabilities. It is front-loaded with the core function and avoids fluff, though it could benefit from a slightly more structured format.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (many parameters, no output schema), the description covers the essential purpose but lacks details on output format, behavior for optional parameters, and how it fits with sibling tools. It is adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 0%, the description must compensate for parameter meaning, but it only mentions 'text instructions' and 'existing image' without detailing the required prompt and image parameters. Other parameters like size, watermark, etc., are not referenced, leaving the agent without guidance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it performs image-to-image editing based on an existing image and text instructions. It lists specific editing capabilities (style conversion, material replacement, etc.) and implicitly differentiates from siblings like text-to-image by specifying that it works on an existing image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies it should be used when editing an existing image with text instructions, but it does not explicitly provide when to use or when not to use this tool versus alternatives like seedream_text_to_image or seedream_multi_image_fusion. No direct comparison or exclusion criteria are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

seedream_multi_image_fusionA

多图融合：

根据输入的文本描述和多张参考图片，融合它们的风格、元素等特征来生成新图像。如衣裤鞋帽与模特图融合成穿搭图，人物与风景融合为人物风景图等。

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description indicates the tool generates new images, consistent with annotations (readOnlyHint=false, destructiveHint=false). However, it does not elaborate on side effects, memory usage, or behavior under specific conditions like failed inputs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with an example, conveying essential information without waste. It could be slightly more structured but is well-suited for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the core functionality but omits output details (e.g., format) and prerequisites. The rich schema compensates partially, but without an output schema, more contextual guidance would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool description adds no parameter-specific details beyond the schema, but the nested schema provides comprehensive descriptions for each field. The description's lack of parameter info is acceptable as the schema already covers semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'multi-image fusion' and provides specific examples like merging clothing with models or people with landscapes, making the tool's purpose unmistakable and distinguishing it from siblings like text-to-image or image-to-image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives examples of when to use (e.g., outfit creation, portrait with scenery) but does not explicitly state when not to use or offer direct comparisons to sibling tools, leaving the agent to infer usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

seedream_sequential_generationA

组图输出：

支持通过一张或者多张图片和文字信息，生成漫画分镜、品牌视觉等一组内容关联的图片。

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description indicates image generation but does not disclose additional behavioral traits beyond annotations (readOnlyHint=false, destructiveHint=false). No mention of auth, rate limits, model-specific constraints, or output format. Schema provides some parameter details but description lacks behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence (27 characters) that immediately states the core purpose and examples. No superfluous text; it is optimally concise and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (many parameters, no output schema, minimal annotations), the description is adequate but leaves out important context like the sequential nature, response format, and model-specific limitations. Schema compensates partially, but overall completeness is average.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool description does not explain any parameters; the input schema has full descriptions for each parameter (high coverage). Thus the description adds no value beyond what's already in the schema, justifying the baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a set of related images (group image output) from text and optional images, with examples like comic panels and brand visuals. It distinctly differs from sibling tools (seedream_browse_images, seedream_image_to_image, etc.) by focusing on sequential generation of multiple related images.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for generating groups of related images but does not explicitly state when to use it over alternatives or provide any exclusion criteria. No guidance on prerequisites or when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

seedream_text_to_imageC

文生图：

通过给模型提供清晰准确的文字指令，即可快速获得符合描述的高质量单张图片。

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are minimal (readOnlyHint false, etc.). Description adds only 'quickly obtain' and 'high-quality', lacking behavioral details like cost, rate limits, or side effects. The agent may not know if generation is expensive or time-consuming.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words, front-loaded with core purpose. Could be more detailed without sacrificing conciseness, but it is efficiently structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having many parameters and sibling tools, the description is too brief. It lacks output details, parameter constraints, and usage context, making it insufficient for complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% – description does not explain any parameters. The schema itself has descriptions for each property, but the description fails to compensate for the low coverage, offering no added meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (文生图 = text-to-image) and resource (single high-quality image from text). It distinguishes from sibling tools like image_to_image or multi_image_fusion by emphasizing text input and single image output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Does not mention when not to use it or provide context for selecting between siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: browsing, text-to-image, image editing, multi-image fusion, and sequential generation. No overlapping functionality.

Naming Consistency5/5

All tools follow the consistent 'seedream_verb_noun' snake_case pattern (e.g., seedream_text_to_image). No mixing of conventions.

Tool Count5/5

With 5 tools, the server is well-scoped for image generation tasks. Each tool covers a distinct operation without unnecessary bloat or gaps.

Completeness4/5

Core image generation workflows (text-to-image, editing, fusion, sequential) are covered. Minor gap: no tool for retrieving image metadata or management, but not essential for generation.

Maintenance

ActivityActive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tengmmvp/Seedream_MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server