mcp-seedream-pro

SeedreamMCP

Model Context Protocol（MCP）に対応した、AceDataCloud APIを通じてByteDanceのSeedreamモデルを使用する、AI 画像生成・編集用サーバーです。

Claude、VS Code、またはMCP対応クライアントから直接、AI画像を生成・編集できます。

特長

• テキストから画像を生成 — テキストプロンプトから高品質な画像を作成します（中国語・英語）。
• 画像編集 — 既存の画像を編集します。透明背景でのPro編集にも対応しています。
• 複数のモデル — Seedream v5.0（フラッグシップ）、v4.5、v4.0に対応しています。
• レイヤー分解 — 1枚の画像を、ベース画像と最大16枚の編集可能な透明PNGレイヤーに分割します。
• 複数の解像度 — Proは1K／1.5K／2K、Liteは2K／3K／4Kに対応し、カスタムサイズも指定できます。
• 連続生成 — 関連する画像を順番に生成します（5.0 Lite／4.5／4.0）。
• ウェブ検索 — 必要に応じて、5.0 Liteで最新のウェブ情報を利用できます。
• タスクの追跡 — 生成の進捗を監視し、結果を取得できます。

ツール一覧

ツール	説明
seedream_generate_image	ByteDanceのSeedreamモデルを使用して、テキストプロンプトからAI画像を生成します。
seedream_edit_image	Seedream 5.0 Proの透明背景モードを含め、画像を編集します。
seedream_decompose_image	1枚の画像をベース画像と、位置情報付きの最大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ストリーミングを行うには、MCPの非同期送信とstreamを組み合わせるのではなく、REST APIまたはCLIを呼び出してください。

接続：ホスト型 OAuth、API トークン、またはローカル stdio

ホスト型エンドポイントは https://seedream.mcp.acedata.cloud/mcp です。MCP クライアントで次のいずれかの方法を選択してください。

方法	使用する場合	認証情報の設定
ホスト型 OAuth	クライアントがリモート MCP OAuth に対応している場合	URL だけを追加してから、AceDataCloud にサインインし、アクセスを承認します。トークンをクライアント設定に貼り付ける必要はありません。
ホスト型 API トークン	クライアントで OAuth を完了できない場合、または明示的な連携用認証情報が必要な場合	AceDataCloud API トークンを Authorization: Bearer … ヘッダーで送信します。ローカルのシークレットストアまたは環境変数に保存してください。
ローカル stdio	クライアントがローカル MCP プロセスを実行する場合	mcp-seedream-pro をインストールし、ACEDATACLOUD_API_TOKEN をそのプロセスに渡します。この方法でも AceDataCloud API を呼び出します。

ホスト型サービスは OAuth メタデータと Dynamic Client Registration（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 では、サーバーを追加するときにシェルがトークンを展開します。保存されたユーザー 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 設定 UI または 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 をコピーせず、各クライアントの最新の UI に従ってください。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 を使用するには、uv が PATH 上にある必要があります。

{
  "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	1 件のタスクのステータスと結果を照会します
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 アートの作成 — 魅力的なアートワーク、イラスト、デジタルアートを生成します
• 商品写真 — プロ品質の商品シーンの構図を作成します
• コンテンツ作成 — ブログ、ソーシャルメディア、マーケティング向けの画像を生成します
• バーチャル試着 — さまざまなモデルに服を着せたイメージを確認します
• スタイル変換 — 写真をさまざまなアートスタイルに変換します
• ゲームデザイン — コンセプトアート、キャラクターデザイン、環境デザイン
• E コマース — 商品のモックアップ、ライフスタイル写真、バナー画像

ドキュメント

ドキュメント

ライセンス

MIT ライセンス - 詳細はLICENSEファイルをご覧ください。

リンク

• AceDataCloud プラットフォーム
• Seedream API ドキュメント
• MCP プロトコル
• GitHub リポジトリ
• PyPI パッケージ