SeedreamMCP

Name: SeedreamMCP
Author: AceDataCloud

PyPI version PyPI downloads Python 3.10+ License: MIT MCP

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

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

功能特性

文本生成图像 (Text-to-Image) — 根据文本提示词（中英文）创建高质量图像
图像编辑 (Image Editing) — 使用 AI 修改现有图像（风格迁移、背景更换、虚拟试穿）
多种模型 — Seedream v5.0（旗舰版）、v4.5、v4.0、v3.0 T2I、SeedEdit v3.0 I2I
多分辨率 — 支持 1K、2K、3K、4K、自适应及自定义尺寸
种子控制 (Seed Control) — 通过种子参数实现可复现的结果（v3 模型）
序列生成 — 按顺序生成相关图像（v4.5/v4.0）
流式传输 — 渐进式图像交付（v4.5/v4.0）
任务追踪 — 监控生成进度并获取结果

工具参考

工具	描述
`seedream_generate_image`	使用字节跳动 Seedream 模型根据文本提示词生成 AI 图像。
`seedream_edit_image`	使用字节跳动 Seedream/SeedEdit 模型编辑或修改现有图像。
`seedream_get_task`	查询 Seedream 图像生成或编辑任务的状态和结果。
`seedream_get_tasks_batch`	一次性查询多个 Seedream 图像任务。
`seedream_list_models`	列出所有可用的 Seedream 模型及其功能和定价。
`seedream_list_sizes`	列出 Seedream 所有可用的图像尺寸和分辨率选项。

快速入门

1. 获取 API Token

在 AceDataCloud 平台注册账号
前往 API 文档页面
点击 “Acquire” 获取您的 API token
复制该 token 以备后用

2. 使用托管服务器（推荐）

AceDataCloud 托管了一个 MCP 服务器 —— 无需本地安装。

端点： https://seedream.mcp.acedata.cloud/mcp

所有请求都需要 Bearer token。请使用第 1 步中获取的 API token。

Claude.ai

通过 OAuth 直接在 Claude.ai 上连接 —— 无需 API token：

前往 Claude.ai 设置 (Settings) → 集成 (Integrations) → 添加更多 (Add More)
输入服务器 URL: https://seedream.mcp.acedata.cloud/mcp
完成 OAuth 登录流程
开始在对话中使用这些工具

Claude Desktop

添加到您的配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "seedream": {
      "type": "streamable-http",
      "url": "https://seedream.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Cursor / Windsurf

添加到您的 MCP 配置文件（.cursor/mcp.json 或 .windsurf/mcp.json）：

{
  "mcpServers": {
    "seedream": {
      "type": "streamable-http",
      "url": "https://seedream.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

VS Code (Copilot)

添加到您的 VS Code MCP 配置文件（.vscode/mcp.json）：

{
  "servers": {
    "seedream": {
      "type": "streamable-http",
      "url": "https://seedream.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

或者为 VS Code 安装 Ace Data Cloud MCP 扩展，该扩展捆绑了所有 15 个 MCP 服务器，支持一键设置。

JetBrains IDEs

前往 设置 (Settings) → 工具 (Tools) → AI Assistant → Model Context Protocol (MCP)
点击 添加 (Add) → HTTP
粘贴：

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

Claude Code

Claude Code 原生支持 MCP 服务器：

claude mcp add seedream --transport http https://seedream.mcp.acedata.cloud/mcp \
  -h "Authorization: Bearer YOUR_API_TOKEN"

或者添加到您项目的 .mcp.json 中：

{
  "mcpServers": {
    "seedream": {
      "type": "streamable-http",
      "url": "https://seedream.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Cline

添加到 Cline 的 MCP 设置 (.cline/mcp_settings.json)：

{
  "mcpServers": {
    "seedream": {
      "type": "streamable-http",
      "url": "https://seedream.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Amazon Q Developer

添加到您的 MCP 配置中：

{
  "mcpServers": {
    "seedream": {
      "type": "streamable-http",
      "url": "https://seedream.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Roo Code

添加到 Roo Code 的 MCP 设置中：

{
  "mcpServers": {
    "seedream": {
      "type": "streamable-http",
      "url": "https://seedream.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Continue.dev

添加到 .continue/config.yaml：

mcpServers:
  - name: seedream
    type: streamable-http
    url: https://seedream.mcp.acedata.cloud/mcp
    headers:
      Authorization: "Bearer YOUR_API_TOKEN"

Zed

添加到 Zed 的设置 (~/.config/zed/settings.json)：

{
  "language_models": {
    "mcp_servers": {
      "seedream": {
        "url": "https://seedream.mcp.acedata.cloud/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_TOKEN"
        }
      }
    }
  }
}

cURL 测试

# Health check (no auth required)
curl https://seedream.mcp.acedata.cloud/health

# MCP initialize
curl -X POST https://seedream.mcp.acedata.cloud/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

3. 或本地运行（替代方案）

如果您更喜欢在自己的机器上运行服务器：

# Install from PyPI
pip install mcp-seedream-pro
# or
uvx mcp-seedream-pro

# Set your API token
export ACEDATACLOUD_API_TOKEN="your_token_here"

# Run (stdio mode for Claude Desktop / local clients)
mcp-seedream-pro

# Run (HTTP mode for remote access)
mcp-seedream-pro --transport http --port 8000

Claude Desktop (本地)

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

Docker (自托管)

docker pull ghcr.io/acedatacloud/mcp-seedream-pro:latest
docker run -p 8000:8000 ghcr.io/acedatacloud/mcp-seedream-pro:latest

客户端使用各自的 Bearer token 进行连接 —— 服务器会从每个请求的 Authorization 标头中提取 token。

可用工具

图像生成与编辑

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

任务管理

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

信息

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

可用模型

模型	版本	类型	最佳用途	价格
`doubao-seedream-5-0-260128`	v5.0	文本生成图像	最佳质量，最新旗舰，支持网页搜索	~$0.040/张
`doubao-seedream-4-5-251128`	v4.5	文本生成图像	前旗舰版，质量优异	~$0.037/张
`doubao-seedream-4-0-250828`	v4.0	文本生成图像	性价比最高，任务处理量大	~$0.030/张
`doubao-seedream-3-0-t2i-250415`	v3.0	文本生成图像	可复现结果	~$0.038/张
`doubao-seededit-3-0-i2i-250628`	v3.0	图像生成图像	图像编辑	~$0.046/张

使用示例

根据提示词生成图像

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]

可复现生成

User: Generate a landscape and make sure I can recreate the exact same image later

Claude: I'll use the v3 model with a fixed seed.
[Calls seedream_generate_image with model=doubao-seedream-3-0-t2i-250415, seed=42]

配置

环境变量

变量	描述	默认值
`ACEDATACLOUD_API_TOKEN`	来自 AceDataCloud 的 API token	必需
`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 文件。