mcp-seedream-pro

SeedreamMCP

通过 AceDataCloud API 使用字节跳动的 Seedream模型进行 AI 图像生成和编辑的 Model Context Protocol (MCP) 服务。

可直接在 Claude、VS Code 或任何兼容 MCP 的客户端中生成和编辑 AI 图像。

功能

• 文生图 — 根据文本提示词创建高质量图像（支持中文和英文）
• 图像编辑 — 修改现有图像，包括支持透明背景的 Pro 编辑
• 多种模型 — Seedream v5.0（旗舰版）、v4.5 和 v4.0
• 图层分解 — 将一张图像拆分为一个底图和最多 16 个可编辑的透明 PNG 图层
• 多种分辨率 — Pro 支持 1K/1.5K/2K；Lite 支持 2K/3K/4K；支持自定义尺寸
• 连续生成 — 按顺序生成相关图像（5.0 Lite/4.5/4.0）
• 网页搜索 — 必要时让 5.0 Lite 使用最新的网页信息
• 任务跟踪 — 监控生成进度并获取结果

工具参考

工具	描述
seedream_generate_image	使用字节跳动的 Seedream 模型，根据文本提示词生成 AI 图像。
seedream_edit_image	编辑图像，包括 Seedream 5.0 Pro 透明背景模式。
seedream_decompose_image	将一张图像拆分为一个底图和最多 16 个带位置的透明图层。
seedream_get_task	查询 Seedream 图像生成或编辑任务的状态和结果。
seedream_get_tasks_batch	一次查询多个 Seedream 图像任务。
seedream_list_models	列出所有可用的 Seedream 模型及其功能和价格。
seedream_list_sizes	列出 Seedream 所有可用的图像尺寸和分辨率选项。

Seedream 5.0 功能对照表

功能	5.0 Pro	5.0 Lite
单张图像生成/编辑	是	是
图层分解 / 透明背景	是	否
连续生成图像 / 网页搜索	否	是
提示词优化	标准、快速	标准
预设尺寸	1K、1.5K、2K	2K、3K、4K

MCP 图像工具会异步提交任务并返回任务 ID。请使用 seedream_get_task 直到任务完成。如需实时 NDJSON 流式传输，请调用 REST API 或 CLI，而不要将 stream 与 MCP 异步提交结合使用。

连接：托管 OAuth、API 令牌或本地 stdio

托管端点为 https://seedream.mcp.acedata.cloud/mcp。为 MCP 客户端选择一种连接方式：

方式	适用场景	凭据设置
托管 OAuth	客户端支持远程 MCP OAuth	只需添加 URL，然后登录 AceDataCloud 并批准访问。无需在客户端配置中粘贴令牌。
托管 API 令牌	客户端无法完成 OAuth，或你需要明确的集成凭据	在 Authorization: Bearer … 标头中发送 AceDataCloud API 令牌。将令牌保存在本地密钥存储或环境变量中。
本地 stdio	客户端运行本地 MCP 进程	安装 mcp-seedream-pro，并将 ACEDATACLOUD_API_TOKEN 传递给该进程。它仍会调用 AceDataCloud API。

托管服务提供 OAuth 元数据和动态客户端注册（DCR）。DCR 注册的是客户端应用；它不是 API 密钥。 OAuth 会为你登录，客户端随后发送生成的 Bearer 令牌；它可能会复用或创建该账户的 API 凭据。通过浏览器登录仍需要 AceDataCloud 账户。托管服务可能按用量计费：在执行实际操作前，请查看当前服务文档和显示的价格。同一服务不要同时配置 OAuth 登录和固定的 Authorization 标头。

托管 OAuth 示例

• Claude 和 Claude Desktop 聊天： 在 Customize → Connectors → Add custom connector 中添加远程自定义连接器，输入 https://seedream.mcp.acedata.cloud/mcp，选择登录；如果 Claude 询问如何注册其 OAuth 客户端，请选择 Register automatically。完成授权。Claude Desktop 的本地 claude_desktop_config.json 是另一种独立配置方式。Claude 连接器指南。
• Claude Code： 运行 claude mcp add --transport http --scope user seedream https://seedream.mcp.acedata.cloud/mcp，然后启动 claude，打开 /mcp，并验证 Seedream 服务。Claude Code MCP 指南。
• Cursor： 只需添加远程服务 https://seedream.mcp.acedata.cloud/mcp。对于项目配置，将以下条目合并到 <project>/.cursor/mcp.json；个人使用则使用 ~/.cursor/mcp.json。Cursor MCP 指南。
• VS Code / Copilot： 运行 MCP: Add Server，选择 HTTP，输入 https://seedream.mcp.acedata.cloud/mcp，然后完成浏览器登录。新的可移植工作区配置使用 <project>/.mcp.json；以下 VS Code 专用格式使用 <project>/.vscode/mcp.json 或用户配置文件。检查 MCP: List Servers。VS Code MCP 设置。
• Codex： 运行 codex mcp add seedream --url https://seedream.mcp.acedata.cloud/mcp，然后运行 codex mcp login seedream。用户设置位于 ~/.codex/config.toml。Codex 官方 MCP 指南。

Cursor 项目配置（OAuth）：

{
  "mcpServers": {
    "seedream": {"url": "https://seedream.mcp.acedata.cloud/mcp"}
  }
}

VS Code 专用工作区配置（OAuth）：

{
  "servers": {
    "seedream": {"type": "http", "url": "https://seedream.mcp.acedata.cloud/mcp"}
  }
}

托管 API 令牌

1. 打开 Ace Data Cloud → Applications。登录，或先注册账号。
2. 找到 General application。如果尚未创建，请选择 Initialize General Application。通用密钥可使用账号可用的服务；专用应用的密钥则仅限其对应服务。检查所需的服务／模型访问权限以及当前定价。
3. 从应用卡片复制 API Key，或打开 Keys / Manage Keys → Create，为此集成创建单独的密钥。为密钥设置一个易于识别的名称，以便单独撤销或轮换。
4. 创建密钥时，检查 Expiration Time、Set Usage Limitation 和 Allowed APIs。仅启用所需的限制，并允许将要调用的操作，然后点击 Create，再从密钥列表中复制令牌。查询任务并不意味着获准提交生成请求。确认应用余额足以支付首次请求；任何试用额度以账号当前显示的额度为准。
5. 仅复制令牌值，不要包含引号、空格或 Bearer 。API Key／API Token 字段需要填写此原始值；只有手动配置 HTTP Authorization 标头时才需要加上 Bearer 前缀。platform-... 账号管理令牌不能代替生成 API 密钥。

将密钥保存在客户端的凭据存储中，或保存在下方所示的环境变量中。切勿将其放入提示词、共享工作流、屏幕截图或 Git 提交中。如果身份验证失败，请检查复制的完整值、应用／服务访问权限、有效期、使用限制和余额，再创建其他密钥。

固定的 Bearer 标头会绕过 OAuth。如果标头无效，请先将其移除，再尝试浏览器登录；请将已保存的凭据妥善保密。

对于 Claude Code，添加服务时，shell 会展开令牌；请将保存的用户 MCP 配置视为机密信息：

export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
claude mcp add --transport http --scope user seedream https://seedream.mcp.acedata.cloud/mcp \
  --header "Authorization: Bearer $ACEDATACLOUD_API_TOKEN"

对于 Claude Code 项目配置，请在 <project>/.mcp.json 中填写变量引用，并在启动 Claude Code 的环境中设置该变量：

{
  "mcpServers": {
    "seedream": {
      "type": "http",
      "url": "https://seedream.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${ACEDATACLOUD_API_TOKEN}"}
    }
  }
}

Cursor 在 ~/.cursor/mcp.json 或未提交的项目配置中使用不同的环境变量语法：

{
  "mcpServers": {
    "seedream": {
      "url": "https://seedream.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${env:ACEDATACLOUD_API_TOKEN}"}
    }
  }
}

在 VS Code 中，运行 MCP: Open User Configuration，并合并此服务及其隐藏输入；${input:...} 适用于 VS Code 的用户／工作区格式，不能移植到 Agent Host 的 .mcp.json 格式：

{
  "inputs": [
    {"id": "acedata-seedream-token", "type": "promptString", "description": "AceDataCloud API token", "password": true}
  ],
  "servers": {
    "seedream": {
      "type": "http",
      "url": "https://seedream.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${input:acedata-seedream-token}"}
    }
  }
}

对于 Cline，请使用其 MCP 配置界面或 CLI 文件 ~/.cline/data/settings/cline_mcp_settings.json；其远程传输值为 streamableHttp。对于 JetBrains AI Assistant，请从 Settings → Tools → AI Assistant → Model Context Protocol (MCP) 添加远程 URL。对于 Zed，若使用 OAuth，请添加仅包含 URL 的 context_servers 条目；或者添加本地 Bearer 标头。这些客户端使用不同的配置架构；请按照各自当前的界面操作，不要直接复制其他客户端的 JSON。Cline · JetBrains · Zed。

本地 stdio

安装软件包，并为本地进程提供 API 令牌：

python -m pip install mcp-seedream-pro
export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
mcp-seedream-pro

对于 Claude Desktop 本地 MCP，请将此条目合并到其开发者设置打开的文件中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）。uvx 要求 PATH 中包含 uv：

{
  "mcpServers": {
    "seedream": {
      "command": "uvx",
      "args": ["mcp-seedream-pro"],
      "env": {"ACEDATACLOUD_API_TOKEN": "YOUR_API_TOKEN"}
    }
  }
}

请妥善保管此用户级文件。可自托管的 HTTP 服务使用 mcp-seedream-pro --transport http --port 8000；只有在具备适当网络和 TLS 控制措施的情况下才对外开放。本地执行仍会调用 AceDataCloud API。

使用服务前的检查

1. https://seedream.mcp.acedata.cloud/health 返回 {"status":"ok"} 仅表示端点可访问。
2. 确认 MCP 客户端已加载工具。seedream_list_models 是本地参考工具，不会产生生成 API 费用；它无法验证下游 API 访问权限或余额。生成、编辑和分解会创建消耗积分的任务，并标记为只读以外的操作。这些注释描述的是操作；客户端版本、权限设置和组织策略决定客户端是否会请求批准。允许付费操作前，请检查输入和当前价格。
3. 如果需要完整的 API 检查，请先查看当前服务文档和显示的价格，然后使用你自己的有效输入调用 seedream_generate_image。如果结果包含任务 ID，请对同一 ID 调用 seedream_get_task，直至任务成功或失败。请勿仅为检查进度而重新提交操作。

遇到 401 时，请检查客户端使用了哪种身份验证方式，以及令牌或 OAuth 会话是否有效。403 可能表示账户权限问题或内容审核失败；请查看返回的错误信息。余额不足和下游服务故障需要分别排查。工具已列出或任务已提交，并不代表操作成功。

可用工具

图像生成与编辑

工具	描述
seedream_generate_image	根据文本提示词生成图像
seedream_edit_image	使用 AI 编辑或修改现有图像

任务管理

工具	描述
seedream_get_task	查询单个任务的状态和结果
seedream_get_tasks_batch	一次查询多个任务

信息

工具	描述
seedream_list_models	列出可用模型及其功能
seedream_list_sizes	列出可用图像尺寸选项

可用模型

模型	版本	类型	适用场景	价格
doubao-seedream-5-0-pro-260628	v5.0 Pro	生成/编辑	单张图像、透明背景、图层分解	分级积分
doubao-seedream-5-0-lite-260128	v5.0 Lite	文生图	顺序生成、流式传输、网络搜索	查看实时价格
doubao-seedream-4-5-251128	v4.5	文生图	前代旗舰，画质出色	查看实时价格
doubao-seedream-4-0-250828	v4.0	文生图	性价比最高，适用于多数任务	查看实时价格

使用示例

根据提示词生成图像

User: Create a photorealistic image of a cat in a garden

Claude: I'll generate that image for you.
[Calls seedream_generate_image with detailed prompt]
→ Returns task_id and image URL

图像编辑

User: Change the background of this photo to a beach
[Provides image URL]

Claude: I'll edit that image for you.
[Calls seedream_edit_image with image URL and edit description]

支持中文提示词

User: 生成一幅中国山水画，有远山、流水和古松

Claude: 好的，我来为您生成这幅山水画。
[Calls seedream_generate_image with Chinese prompt]

配置

环境变量

变量	描述	默认值
ACEDATACLOUD_API_TOKEN	AceDataCloud 的 API 令牌	必填
ACEDATACLOUD_API_BASE_URL	API 基础 URL	https://api.acedata.cloud
ACEDATACLOUD_OAUTH_CLIENT_ID	OAuth 客户端 ID（托管模式）	—
ACEDATACLOUD_PLATFORM_BASE_URL	平台基础 URL	https://platform.acedata.cloud
SEEDREAM_REQUEST_TIMEOUT	请求超时时间（秒）	1800
LOG_LEVEL	日志级别	INFO

命令行选项

mcp-seedream-pro --help

Options:
  --version          Show version
  --transport        Transport mode: stdio (default) or http
  --port             Port for HTTP transport (default: 8000)

开发

设置开发环境

# Clone repository
git clone https://github.com/AceDataCloud/SeedreamMCP.git
cd SeedreamMCP

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

# Install with dev dependencies
pip install -e ".[dev,test]"

运行测试

# Run unit tests
pytest

# Run with coverage
pytest --cov=core --cov=tools

# Run integration tests (requires API token)
pytest -m integration

代码质量

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy core tools main.py

构建与发布

# Install build dependencies
pip install -e ".[release]"

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

项目结构

SeedreamMCP/
├── core/                   # Core modules
│   ├── __init__.py
│   ├── client.py          # HTTP client for Seedream API
│   ├── config.py          # Configuration management
│   ├── exceptions.py      # Custom exceptions
│   ├── server.py          # MCP server initialization
│   ├── types.py           # Type definitions
│   └── utils.py           # Utility functions
├── tools/                  # MCP tool definitions
│   ├── __init__.py
│   ├── image_tools.py     # Image generation/editing tools
│   ├── task_tools.py      # Task query tools
│   └── info_tools.py      # Model & size info tools
├── prompts/                # MCP prompt templates
│   └── __init__.py
├── tests/                  # Test suite
│   ├── conftest.py
│   ├── test_config.py
│   └── test_utils.py
├── deploy/                 # Deployment configs
│   ├── run.sh
│   └── production/
│       ├── deployment.yaml
│       ├── ingress.yaml
│       └── service.yaml
├── .github/                # GitHub Actions workflows
│   ├── dependabot.yml
│   └── workflows/
│       ├── ci.yaml
│       ├── claude.yml
│       ├── deploy.yaml
│       └── publish.yml
├── .env.example           # Environment template
├── .gitignore
├── .ruff.toml             # Ruff linter config
├── CHANGELOG.md
├── Dockerfile             # Docker image for HTTP mode
├── docker-compose.yaml    # Docker Compose config
├── LICENSE
├── main.py                # Entry point
├── pyproject.toml         # Project configuration
└── README.md

API 参考

此服务封装了 AceDataCloud Seedream API：

• Seedream Images API — 图像生成与编辑
• Seedream Tasks API — 任务查询

使用场景

• AI 艺术创作 — 生成令人惊艳的艺术作品、插画和数字艺术
• 产品摄影 — 创建专业的产品场景构图
• 内容创作 — 为博客、社交媒体和营销活动生成图像
• 虚拟试穿 — 展示不同模特穿着服装的效果
• 风格迁移 — 将照片转换为不同的艺术风格
• 游戏设计 — 概念艺术、角色设计、环境设计
• 电子商务 — 产品样图、生活方式照片、横幅图像

文档

文档

许可证

MIT 许可证 — 详情请参阅 LICENSE 文件。

链接

• AceDataCloud 平台
• Seedream API 文档
• MCP 协议
• GitHub 仓库
• PyPI 软件包