SoraMCP

Name: SoraMCP
Author: AceDataCloud

PyPI version PyPI downloads Python 3.10+ License: MIT MCP

AceDataCloud API를 통해 Sora를 사용하는 AI 비디오 생성용 Model Context Protocol (MCP) 서버입니다.

Claude, VS Code 또는 MCP 호환 클라이언트에서 직접 AI 비디오를 생성하세요.

주요 기능

텍스트-비디오 - 텍스트 설명으로 비디오 생성
이미지-비디오 - 이미지를 애니메이션화하고 참조 이미지로 비디오 생성
캐릭터 비디오 - 서로 다른 장면에서 캐릭터 재사용
비동기 생성 - 프로덕션 워크플로우를 위한 웹훅 콜백
다양한 방향 - 가로 및 세로 비디오 지원
작업 추적 - 생성 진행 상황 모니터링 및 결과 검색

도구 참조

도구	설명
`sora_generate_video`	Sora를 사용하여 텍스트 프롬프트에서 AI 비디오를 생성합니다.
`sora_generate_video_from_image`	Sora를 사용하여 참조 이미지에서 AI 비디오를 생성합니다 (이미지-비디오).
`sora_generate_video_with_character`	참조 비디오의 캐릭터를 포함하는 AI 비디오를 생성합니다.
`sora_generate_video_async`	콜백 알림과 함께 비동기적으로 AI 비디오를 생성합니다.
`sora_generate_video_v2`	Sora 버전 2(파트너 채널)를 사용하여 AI 비디오를 생성합니다.
`sora_generate_video_v2_async`	콜백과 함께 Sora 버전 2를 사용하여 비동기적으로 AI 비디오를 생성합니다.
`sora_get_task`	비디오 생성 작업의 상태와 결과를 조회합니다.
`sora_get_tasks_batch`	여러 비디오 생성 작업을 한 번에 조회합니다.
`sora_list_models`	사용 가능한 모든 Sora 모델과 기능을 나열합니다.
`sora_list_actions`	사용 가능한 모든 Sora API 작업과 해당 도구를 나열합니다.

빠른 시작

1. API 토큰 받기

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

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

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

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

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

Claude.ai

OAuth를 사용하여 Claude.ai에 직접 연결하세요 (API 토큰 불필요):

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

Claude Desktop

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

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

Cursor / Windsurf

MCP 설정에 추가하세요 (.cursor/mcp.json 또는 .windsurf/mcp.json):

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

VS Code (Copilot)

VS Code MCP 설정에 추가하세요 (.vscode/mcp.json):

{
  "servers": {
    "sora": {
      "type": "streamable-http",
      "url": "https://sora.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": {
    "sora": {
      "url": "https://sora.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Claude Code

Claude Code는 MCP 서버를 기본적으로 지원합니다:

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

또는 프로젝트의 .mcp.json에 추가하세요:

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

Cline

Cline의 MCP 설정에 추가하세요 (.cline/mcp_settings.json):

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

Amazon Q Developer

MCP 구성에 추가하세요:

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

Roo Code

Roo Code MCP 설정에 추가하세요:

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

Continue.dev

.continue/config.yaml에 추가하세요:

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

Zed

Zed 설정에 추가하세요 (~/.config/zed/settings.json):

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

cURL 테스트

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

# MCP initialize
curl -X POST https://sora.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-sora
# or
uvx mcp-sora

# Set your API token
export ACEDATACLOUD_API_TOKEN="your_token_here"

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

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

Claude Desktop (로컬)

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

Docker (셀프 호스팅)

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

클라이언트는 자신의 Bearer 토큰으로 연결하며, 서버는 각 요청의 Authorization 헤더에서 토큰을 추출합니다.

사용 가능한 도구

비디오 생성

도구	설명
`sora_generate_video`	텍스트 프롬프트에서 비디오 생성
`sora_generate_video_from_image`	참조 이미지에서 비디오 생성
`sora_generate_video_with_character`	참조 비디오의 캐릭터로 비디오 생성
`sora_generate_video_async`	콜백 알림과 함께 비디오 생성

작업

도구	설명
`sora_get_task`	단일 작업 상태 조회
`sora_get_tasks_batch`	여러 작업 한 번에 조회

정보

도구	설명
`sora_list_models`	사용 가능한 Sora 모델 나열
`sora_list_actions`	사용 가능한 API 작업 나열

사용 예시

프롬프트에서 비디오 생성

User: Create a video of a sunset over mountains

Claude: I'll generate a sunset video for you.
[Calls sora_generate_video with prompt="A beautiful sunset over mountains..."]

이미지에서 생성

User: Animate this image of a city skyline

Claude: I'll bring this image to life.
[Calls sora_generate_video_from_image with image_urls and prompt]

캐릭터 기반 비디오

User: Use the robot character in a new scene

Claude: I'll create a new scene with the robot character.
[Calls sora_generate_video_with_character with character_url and prompt]

사용 가능한 모델

모델	최대 지속 시간	품질	기능
`sora-2`	15초	좋음	표준 생성
`sora-2-pro`	25초	최고	더 높은 품질, 더 긴 비디오

비디오 옵션

크기:

small - 낮은 해상도, 빠른 생성
large - 높은 해상도 (권장)

방향:

landscape - 16:9 (YouTube, 프레젠테이션)
portrait - 9:16 (TikTok, Instagram Stories)

지속 시간:

10초 - 모든 모델
15초 - 모든 모델
25초 - sora-2-pro 전용

구성

환경 변수

변수	설명	기본값
`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`
`SORA_DEFAULT_MODEL`	기본 모델	`sora-2`
`SORA_DEFAULT_SIZE`	기본 비디오 크기	`large`
`SORA_DEFAULT_DURATION`	기본 지속 시간 (초)	`15`
`SORA_DEFAULT_ORIENTATION`	기본 방향	`landscape`
`SORA_REQUEST_TIMEOUT`	요청 타임아웃 (초)	`3600`
`LOG_LEVEL`	로깅 레벨	`INFO`

명령줄 옵션

mcp-sora --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/SoraMCP.git
cd SoraMCP

# 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 tests/test_integration.py -m integration

코드 품질

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy core tools

빌드 및 배포

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

# Build package
python -m build

# Upload to PyPI
twine upload dist/*

프로젝트 구조

SoraMCP/
├── core/                   # Core modules
│   ├── __init__.py
│   ├── client.py          # HTTP client for Sora 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
│   ├── video_tools.py     # Video generation tools
│   ├── task_tools.py      # Task query tools
│   └── info_tools.py      # Information tools
├── prompts/                # MCP prompt templates
│   └── __init__.py
├── tests/                  # Test suite
│   ├── conftest.py
│   ├── test_client.py
│   ├── test_config.py
│   ├── test_integration.py
│   └── test_utils.py
├── deploy/                 # Deployment configs
│   └── production/
│       ├── deployment.yaml
│       ├── ingress.yaml
│       └── service.yaml
├── .env.example           # Environment template
├── .gitignore
├── 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 Sora API를 래핑합니다:

Sora Videos API - 비디오 생성
Sora Tasks API - 작업 쿼리

기여

기여를 환영합니다! 다음 단계를 따라주세요:

저장소를 포크하세요.
기능 브랜치를 만드세요 (git checkout -b feature/amazing).
변경 사항을 커밋하세요 (git commit -m 'Add amazing feature').
브랜치에 푸시하세요 (git push origin feature/amazing).
풀 리퀘스트를 여세요.

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE를 참조하세요.

링크

AceDataCloud에서 사랑을 담아 제작함