Seedream Image MCP

简体中文 · 繁體中文 · English

基于火山引擎 Seedream API 的 AI 图像生成 MCP 工具。

本项目由 智谱 GLM Coding Plan 提供支持

📑 目录

⚡ 快速安装

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.example 创建 .env 供 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 端口，MCP 端点路径为 /mcp；宿主机映射端口由 SEEDREAM_HTTP_PORT 控制，默认 8000。端口映射默认仅绑定回环地址 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 客户端需手动配置凭据。

🔧 客户端配置

推荐通过 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 mcp add seedream-image-mcp --env ARK_API_KEY=your_api_key_here -- uvx seedream-image-mcp

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

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

鉴权方式：网页本身无需令牌即可打开；网页的功能接口在部署配置了令牌时需要验证——在页面中输入后令牌仅存于当前标签页会话，关闭标签页即失效，下次使用需重新输入，不会出现在网址中。仅本机使用且未配置令牌时，全程无需输入任何东西，接口也只接受来自本页面与本机程序的请求。

🛠️ 可用工具

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

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

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

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

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

📐 模型能力

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

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

💰 模型价格

各模型按张计费，单价如下：

计费说明：因审核等原因未成功输出的图片不计费；组图按实际生成的图片数量计费；5.0 Pro 图层拆分按每个图层实际像素档位单独计费，像素档以 261 万像素（约 1.5K）划界。本文价格为参考刊例，完整计费逻辑与最新单价以 火山方舟模型服务计费说明 为准。

📦 可用资源

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

🧠 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)"

技能目录包含以下文件：

🎭 风格预设

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

⚙️ 启动参数

# 配置来源
--config-file TEXT                                 # .env 配置文件路径；指定后不再读取项目根与当前目录的 .env

# 必需配置
--api-key TEXT                                     # API 密钥（推荐用环境变量 ARK_API_KEY；命令行传入会留在进程列表与 shell 历史中）

# 模型与端点
--model [doubao-seedream-5.0-pro|doubao-seedream-5.0|doubao-seedream-5.0-lite|doubao-seedream-4.5|doubao-seedream-4.0]
                                                 # 模型选择；完整 Model ID 或 Endpoint ID 经 SEEDREAM_MODEL_ID 传入 (默认: 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 豁免）

# 日志
--log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]    # 日志级别 (默认: INFO)

# 传输与 Web
--transport [stdio|streamable-http]                # MCP 传输方式 (默认: stdio)
--host TEXT                                        # streamable-http 监听地址 (默认: 127.0.0.1；绑定非回环地址必须配置鉴权令牌与 TLS，否则拒绝启动)
--port INTEGER                                     # streamable-http 监听端口 (默认: 8000，范围 1-65535)
--auth-token TEXT                                  # Bearer 鉴权令牌 (非回环绑定必须配置；推荐用 SEEDREAM_HTTP_AUTH_TOKEN)
--ssl-certfile TEXT                                # TLS 证书文件 (非回环绑定必须配置，与 --ssl-keyfile 成对)
--ssl-keyfile TEXT                                 # TLS 私钥文件 (与 --ssl-certfile 成对)
--insecure-allow-non-tls                           # 允许非回环明文运行 (仅受信反向代理终结 TLS 场景)
--stateless                                        # 无状态模式，仅影响带握手会话的旧规范修订客户端，代价是失去反向通道 (默认关闭)
--web                                              # 开启 Web 操作台，浏览器访问 /web 直接使用 (默认关闭；未传入时按 SEEDREAM_WEB_ENABLED 解析)
--no-web                                           # 关闭 Web 操作台，覆盖 SEEDREAM_WEB_ENABLED 的开启设置
--version                                          # 打印版本号并退出

安全提示：localhost 不被视为回环地址，须按非回环地址要求配置 Bearer 鉴权令牌与 TLS，未配置则拒绝启动；如需免鉴权使用回环地址，请改绑 127.0.0.1 或 ::1。非回环绑定默认按该地址校验 Host 与 Origin 头以防 DNS rebinding；通配绑定（0.0.0.0/::）无法预知访问地址，校验默认关闭，需配置 SEEDREAM_HTTP_ALLOWED_HOSTS 启用。跨源浏览器客户端接入 /mcp（如网页版客户端）另需配置 SEEDREAM_HTTP_ALLOWED_ORIGINS，配置后自动应答跨源预检并放行列表内来源；放行列表内的公网页面同时豁免浏览器的专用网络访问限制，可直接访问本地绑定的服务。生产与容器部署的密钥应经环境变量（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

🔑 环境变量配置

全部配置项、默认值与说明见 .env.example，复制为 .env 后按需修改。

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

.env 加载规则：

• 使用 --config-file 时：仅加载指定文件。
• 未指定 --config-file 时：按“项目根 .env -> 当前工作目录 .env”顺序合并，后者覆盖前者。
• .env 的值不会注入进程环境变量，仅按上述优先级解析后写入配置对象，避免污染全局状态；系统环境变量优先于 .env 文件。

部署注意事项

• 保存目录由服务管理：按天清理与总量配额只作用于图片目录 <数据根目录>/.seedream/images，目录内所有过期的图片文件与空目录都会被删除，不看文件来源；经 save_path 保存到其他目录的文件不受管理。
• 多客户端部署建议显式设置 SEEDREAM_DATA_ROOT：数据根目录默认跟随客户端声明的 MCP Roots 变化，不同客户端的图片会散落在各自目录；显式声明后所有会话共用同一落点，读取范围与数据位置随之确定。
• 有状态会话依赖客户端正确断开：旧版协议客户端的 streamable-http 会话在客户端发送 DELETE 或进程退出时回收，客户端异常退出时会话驻留；大量短连客户端的部署建议改用 --stateless，新版协议客户端无会话、不受此影响。
• Linux 宿主挂载目录属主：容器以 uid 1000 运行，compose 挂载的 ./.seedream 目录需对该用户可写：mkdir -p .seedream && chown 1000:1000 .seedream；Docker Desktop 不受影响。
• 出站连接不走系统代理：API 调用与图片下载固定忽略 HTTP_PROXY 等系统代理环境变量；企业代理环境需保证主机直连公网，或经网络层透明代理转发。

❓ 常见问题

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

👥 贡献者

项目维护者

• @tengmmvp - 项目维护者

重要贡献者

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

📄 许可证

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