SeedreamMCP

Name: SeedreamMCP
Author: AceDataCloud

PyPI version PyPI downloads Python 3.10+ License: MIT MCP

AceDataCloud API를 통해 ByteDance의 Seedream 모델을 사용하는 Model Context Protocol (MCP) 서버입니다.

Claude, VS Code 또는 MCP 호환 클라이언트에서 직접 AI 이미지를 생성하고 편집하세요.

주요 기능

텍스트 기반 이미지 생성 — 텍스트 프롬프트(중국어 및 영어)로 고품질 이미지 생성
이미지 편집 — AI를 사용하여 기존 이미지 수정(스타일 변환, 배경 변경, 가상 피팅)
다중 모델 — Seedream v5.0(플래그십), v4.5, v4.0, v3.0 T2I, SeedEdit v3.0 I2I 지원
다중 해상도 — 1K, 2K, 3K, 4K, 적응형 및 사용자 지정 크기 지원
시드(Seed) 제어 — 시드 매개변수를 통한 결과 재현 가능(v3 모델)
순차적 생성 — 관련 이미지를 순차적으로 생성(v4.5/v4.0)
스트리밍 — 점진적 이미지 전송(v4.5/v4.0)
작업 추적 — 생성 진행 상황 모니터링 및 결과 조회

도구 참조

도구	설명
`seedream_generate_image`	ByteDance의 Seedream 모델을 사용하여 텍스트 프롬프트로 AI 이미지를 생성합니다.
`seedream_edit_image`	ByteDance의 Seedream/SeedEdit 모델을 사용하여 기존 이미지를 편집하거나 수정합니다.
`seedream_get_task`	Seedream 이미지 생성 또는 편집 작업의 상태와 결과를 조회합니다.
`seedream_get_tasks_batch`	여러 Seedream 이미지 작업을 한 번에 조회합니다.
`seedream_list_models`	사용 가능한 모든 Seedream 모델과 그 기능 및 가격을 나열합니다.
`seedream_list_sizes`	Seedream에서 사용 가능한 모든 이미지 크기 및 해상도 옵션을 나열합니다.

빠른 시작

1. API 토큰 받기

AceDataCloud 플랫폼에 가입하세요.
API 문서 페이지로 이동하세요.
**"Acquire"**를 클릭하여 API 토큰을 받으세요.
아래에서 사용할 토큰을 복사하세요.

2. 호스팅 서버 사용 (권장)

AceDataCloud는 관리형 MCP 서버를 호스팅하므로 별도의 로컬 설치가 필요하지 않습니다.

엔드포인트: https://seedream.mcp.acedata.cloud/mcp

모든 요청에는 Bearer 토큰이 필요합니다. 1단계에서 받은 API 토큰을 사용하세요.

Claude.ai

Claude.ai에서 OAuth를 통해 직접 연결하세요 — API 토큰이 필요하지 않습니다:

Claude.ai 설정 → 통합 → 더 추가하기로 이동하세요.
서버 URL 입력: https://seedream.mcp.acedata.cloud/mcp
OAuth 로그인 절차를 완료하세요.
대화에서 도구를 사용하기 시작하세요.

Claude Desktop

설정 파일(~/Library/Application Support/Claude/claude_desktop_config.json, macOS 기준)에 추가하세요:

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

**설정 → 도구 → AI Assistant → Model Context Protocol (MCP)**로 이동하세요.
추가 → 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 토큰으로 연결하며, 서버는 각 요청의 Authorization 헤더에서 토큰을 추출합니다.

사용 가능한 도구

이미지 생성 및 편집

도구	설명
`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 토큰	필수
`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 파일을 참조하세요.