Seedance MCP 연동 가이드

MCP(Model Context Protocol) 은 Anthropic이 출시한 모델 컨텍스트 프로토콜로, AI 모델(예: Claude, GPT 등)이 표준화된 인터페이스를 통해 외부 도구를 호출할 수 있도록 합니다. AceData Cloud에서 제공하는 Seedance MCP Server를 통해 Claude Desktop, VS Code, Cursor 등의 AI 클라이언트에서 바이트댄스 Seedance를 직접 사용하여 AI 동영상을 생성할 수 있습니다.

기능 개요

Seedance MCP Server는 다음과 같은 핵심 기능을 제공합니다:

텍스트로 동영상 생성 — 텍스트 프롬프트를 통해 고품질 동영상 생성
이미지로 동영상 생성 — 이미지를 참고하여 동영상 생성(첫 프레임, 마지막 프레임, 참조 이미지 등의 모드)
다중 모델 지원 — Seedance 1.x, 1.5, 2.0 및 2.5 지원
다양한 해상도 — 480p, 720p, 1080p 지원, 일부 모델은 4k 지원
다양한 화면 비율 — 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 및 adaptive 지원
유연한 길이 — 모델에 따라 2–30초 또는 자동 길이 지원
멀티모달 동영상 — 오디오 생성, 참조 오디오/동영상 및 2.5의 동영상 편집과 연장 지원
작업 조회 — 생성 진행 상황을 모니터링하고 결과 획득

권장: 호스팅 MCP의 OAuth 인증 사용

원격 MCP OAuth를 지원하는 클라이언트에 서버 주소를 추가합니다:

https://seedance.mcp.acedata.cloud/mcp

연결 또는 로그인을 선택하고 Ace Data Cloud에 로그인하여 권한을 확인하고 인증한 다음 도구를 활성화합니다. 이 경로에서는 먼저 API Token을 생성하거나 복사할 필요가 없습니다. 서비스는 OAuth discovery, 동적 클라이언트 등록(DCR) 및 S256 PKCE를 지원합니다. DCR은 클라이언트를 등록하며, 사용자는 여전히 로그인하고 인증해야 하고 API 사용은 정상적으로 과금됩니다.

클라이언트	연동 방식 및 조건
Claude 웹 버전 또는 원격 커넥터를 제공하는 Desktop 버전	커넥터 인터페이스에서 위 주소를 추가하고 인증합니다. 진입점은 버전과 요금제의 영향을 받습니다. 원격 HTTP 구성을 로컬 stdio 구성 파일에 작성하지 마세요.
네이티브 원격 MCP OAuth를 지원하는 VS Code	MCP: Add Server를 실행하고 HTTP를 선택한 후 주소를 입력하고 안내에 따라 로그인합니다. 전용 AceDataCloud 확장 프로그램은 별도의 API Key 설정을 사용합니다.
기타 클라이언트	현재 버전이 원격 HTTP, OAuth/DCR을 지원하는지 확인하고 해당 클라이언트의 구성 설명을 사용합니다. 구성 파일 형식은 서로 다른 클라이언트 간에 공통으로 사용할 수 없습니다.

API Token 대체 경로

로컬 stdio, 자체 호스팅 또는 원격 OAuth를 지원하지 않는 클라이언트는 API Token을 사용합니다. Ace Data Cloud 플랫폼에 로그인하고 서비스를 선택하여 필요한 권한의 API 자격 증명을 생성합니다. Token은 클라이언트의 자격 증명 설정 또는 로컬 환경 변수에 저장하고 URL, 채팅 내용 또는 버전 관리 저장소에 넣지 마세요. 서로 다른 클라이언트의 HTTP Header 구성은 해당 버전의 설명에 따라 작성해야 합니다. 오픈 소스 MCP를 설치하거나 인증을 완료한다고 해서 무료 할당량을 얻는 것은 아니며, 생성 시간이나 상업적 사용 권한을 보장하지도 않습니다. 생성 전에 현재 서비스 가격, 잔액 및 적용 약관을 확인하세요.

방법 2: 로컬 실행(pip / uvx 설치)

로컬 stdio, 사용자 지정 코드 또는 자체 호스팅이 필요한 경우 로컬에서 MCP Server를 시작할 수 있습니다. 생성은 여전히 네트워크를 통해 API를 호출해야 하며 오프라인 추론이 아닙니다.

설치

pip 설치(권장):

pip install mcp-seedance

또는 소스 코드 설치:

git clone https://github.com/AceDataCloud/SeedanceMCP.git
cd SeedanceMCP
pip install -e .

설치가 완료되면 mcp-seedance 명령을 사용하여 서비스를 시작할 수 있습니다.

Claude Desktop에서 사용(로컬)

Claude Desktop 구성 파일을 편집합니다:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

다음 구성을 추가합니다:

{
  "mcpServers": {
    "seedance": {
      "command": "mcp-seedance",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

uvx를 사용하는 경우(패키지를 미리 설치할 필요 없음):

{
  "mcpServers": {
    "seedance": {
      "command": "uvx",
      "args": ["mcp-seedance"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

구성을 저장한 후 Claude Desktop을 재시작하면 적용됩니다.

VS Code에서 사용(로컬)

프로젝트 루트 디렉터리에 .vscode/mcp.json을 생성합니다:

{
  "servers": {
    "seedance": {
      "command": "mcp-seedance",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

또는 uvx를 사용합니다:

{
  "servers": {
    "seedance": {
      "command": "uvx",
      "args": ["mcp-seedance"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

기타 로컬 클라이언트는 현재 버전의 stdio 구성 설명에 따라 command, args 및 env를 작성하고, VS Code 구성을 범용 형식으로 직접 사용하지 마세요.

결과 검증 및 일반적인 실패

클라이언트에 간단한 동영상 작품 하나를 생성하도록 요청하고, 작업 번호를 보관한 뒤 최종 성공 상태가 될 때까지 동일한 작업을 조회한 다음 최종 링크를 열거나 재생하세요. 연결 성공, 도구 목록 로드, HTTP 200, 작업 번호 및 처리 중 미리보기는 모두 최종 결과물을 의미하지 않습니다. 401이 발생하면 다시 로그인하거나 Token과 권한을 확인하세요. 잔액이 부족한 경우 청구 내역을 확인하세요. 작업 처리 중에는 계속 조회하세요. 최종 실패 시 오류를 읽은 후 재시도 여부를 결정하세요. 새 생성에는 다시 과금될 수 있습니다.

사용 가능한 도구 목록

도구명	설명
`seedance_generate_video`	텍스트 프롬프트를 통해 동영상 생성
`seedance_generate_video_from_image`	이미지를 참고하여 동영상 생성
`seedance_get_task`	단일 작업 상태 조회
`seedance_get_tasks_batch`	작업 상태 일괄 조회
`seedance_list_models`	사용 가능한 모든 모델 및 해당 기능 나열
`seedance_list_resolutions`	사용 가능한 해상도 및 화면 비율 나열
`seedance_list_actions`	사용 가능한 모든 도구 및 워크플로 예시 나열

사용 예시

구성이 완료되면 AI 클라이언트에서 자연어로 직접 이러한 기능을 호출할 수 있습니다. 예를 들면:

「Seedance로 도시 거리 타임랩스 동영상을 생성해 줘」
「이 사진을 첫 프레임으로 사용하여 8초짜리 동영상을 생성해 줘」
「1080p 세로형 9:16 짧은 동영상을 생성해 줘」
「Seedance 1.5 Pro 모델로 오디오가 포함된 동영상을 생성해 줘」

추가 정보

GitHub 저장소: AceDataCloud/SeedanceMCP
PyPI 패키지: mcp-seedance
API 문서: Seedance 동영상 생성 API

​기능 개요

​권장: 호스팅 MCP의 OAuth 인증 사용

​API Token 대체 경로

​방법 2: 로컬 실행(pip / uvx 설치)

​설치

​Claude Desktop에서 사용(로컬)

​VS Code에서 사용(로컬)

​결과 검증 및 일반적인 실패

​사용 가능한 도구 목록

​사용 예시

​추가 정보