Metadata-Version: 2.5
Name: seedream-image-mcp
Version: 3.0.2
Summary: 基于火山引擎 Seedream API 的 MCP 工具，支持 AI 图像生成功能
Project-URL: Homepage, https://github.com/tengmmvp/Seedream_MCP
Project-URL: Documentation, https://github.com/tengmmvp/Seedream_MCP#readme
Project-URL: Repository, https://github.com/tengmmvp/Seedream_MCP.git
Project-URL: Bug Tracker, https://github.com/tengmmvp/Seedream_MCP/issues
Author-email: TengMMVP <tengmmvp@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,image-generation,mcp,model-context-protocol,seedream,volcengine
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: aiofiles<26,>=24.1.0
Requires-Dist: aiohttp<4,>=3.11.0
Requires-Dist: httpx<1,>=0.28.0
Requires-Dist: loguru<1,>=0.7.2
Requires-Dist: mcp<3.0.0,>=2.0.0
Requires-Dist: pillow-heif<2,>=1.5.0
Requires-Dist: pillow<13,>=11.3.0
Requires-Dist: pydantic<3,>=2.12.0
Requires-Dist: python-dotenv<2,>=1.0.0
Requires-Dist: starlette<2,>=0.38.0
Requires-Dist: uvicorn<1,>=0.47.0
Description-Content-Type: text/markdown

<h1 align="center">Seedream Image MCP</h1>

<p align="center">
  <a href="./README.md">简体中文</a>
  ·
  <a href="./README.zh-TW.md">繁體中文</a>
  ·
  <a href="./README.en.md">English</a>
</p>

<div align="center">
  <img src="https://img.shields.io/github/v/release/tengmmvp/Seedream_MCP?display_name=tag&sort=semver&label=Release&style=for-the-badge&color=4C51BF" alt="Version"/>
  <img src="https://img.shields.io/pypi/v/seedream-image-mcp?label=PyPI&style=for-the-badge&color=F37720" alt="PyPI"/>
  <img src="https://img.shields.io/badge/Python-3.12+-3776AB.svg?style=for-the-badge" alt="Python"/>
  <img src="https://img.shields.io/badge/License-MIT-2DA44E.svg?style=for-the-badge" alt="License"/>
  <a href="https://zread.ai/tengmmvp/Seedream_MCP">
    <img src="https://img.shields.io/badge/Ask_Zread-_.svg?style=for-the-badge&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff" alt="Ask Zread"/>
  </a>
  <br><br>
  <img src="https://raw.githubusercontent.com/tengmmvp/img2code/main/img/doubao-seedream-5-0-pro.jpeg" alt="Seedream MCP" width="670"/>
  <br><br>
  <b>基于火山引擎 Seedream API 的 AI 图像生成 MCP 工具。</b>
</div>

---

<details>
<summary>本项目由 智谱 GLM Coding Plan 提供支持</summary>

<div align="center">
  <a href="https://www.bigmodel.cn/glm-coding?ic=GDEQEW52AC">
    <img src="https://raw.githubusercontent.com/tengmmvp/img2code/main/img/zhipu-glm-coding-plan.png" alt="Powered by 智谱 GLM Coding Plan · 智谱编码套餐" />
  </a>
</div>

</details>

---

## ⚡ 快速安装

### 1. 前置准备

安装 [uv](https://docs.astral.sh/uv/)（包含 `uvx` 命令）：

```bash
# 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"
```

在[火山引擎控制台](https://console.volcengine.com/)获取 API 密钥，通过环境变量 `ARK_API_KEY` 提供。

### 2. 一键启动

```bash
# 通过环境变量提供密钥（推荐）
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](https://pypi.org/project/seedream-image-mcp/) 拉取最新版本并在隔离环境运行——无需 clone 仓库、无需手动创建虚拟环境、无需安装依赖。

### 3. 可选：Docker Compose

```bash
# 下载 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 的客户端同理）：

```json
{
  "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`：

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

<details>
<summary><b>其他客户端配置</b>（Claude Code · Cursor · Cline）</summary>

### Claude Code（命令行一键注册）

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

### Cursor

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

```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`：

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

</details>

> 需要指定模型/尺寸时，追加到 `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 端点。

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

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

## ⚙️ 启动参数

```bash
# 认证与配置来源
--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 面全部强制令牌，免鉴权的仅限无数据的静态页面骨架。

### 使用示例

```bash
# 基础使用
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 张，另独享图层拆分与透明背景能力。

## 🛠️ 可用工具

<details>
<summary><b>1. <code>text_to_image</code></b> — 文生图</summary>

根据文本提示词生成图像。该工具调用外部计费 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` (可选) - 自定义文件名前缀

**调用示例：**

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

</details>

<details>
<summary><b>2. <code>image_to_image</code></b> — 图文生图</summary>

根据输入图像和文本提示生成新图像。该工具调用外部计费 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` (可选) - 自定义文件名前缀

**调用示例：**

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

</details>

<details>
<summary><b>3. <code>multi_image_fusion</code></b> — 多图融合</summary>

将多张图像融合生成新图像。该工具调用外部计费 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` (可选) - 自定义文件名前缀

**调用示例：**

```json
{
  "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"
    ]
  }
}
```

</details>

<details>
<summary><b>4. <code>sequential_generation</code></b> — 组图输出</summary>

连续生成多张图像，支持文生组图、单图生组图、多图生组图（仅 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` (可选) - 自定义文件名前缀

**调用示例：**

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

</details>

<details>
<summary><b>5. <code>browse_images</code></b> — 图片浏览</summary>

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

**参数：**

- `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`

**调用示例：**

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

</details>

## 📦 可用资源

除工具外，服务端还暴露以下 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](https://agentskills.io) 开放标准技能目录，为 AI 客户端提供图像生成的完整方法论，两种方式可用：

- **资源自动发现**：客户端直接读取上表 `skill://` 资源，主文件常驻资源列表，参考文件按需读取
- **手动安装**：将包内 `seedream_mcp/skills/seedream-image-generation/` 整目录拷贝到客户端技能目录，例如 Claude Code 的 `~/.claude/skills/`

```bash
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 命令不存在？**

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

**Q: 如何获取 API 密钥？**
访问 [火山引擎控制台](https://console.volcengine.com/) 创建密钥

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

```bash
# 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
```

## 🧪 本地开发

```bash
# 克隆仓库
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` 文件。

```bash
# 必需配置
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 不受影响。

## 👥 贡献者

### 项目维护者

- **[@tengmmvp](https://github.com/tengmmvp)** - 项目维护者

### 重要贡献者

- **[@caoergou](https://github.com/caoergou)** - 通过 [PR #2](https://github.com/tengmmvp/Seedream_MCP/pull/2) 贡献了 uvx 支持、Docker 容器化配置、GitHub Actions 自动化发布流程，极大简化了项目的安装与部署体验

## 📄 许可证

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