Amazon Nova Reel 1.1 MCP 서버

AWS Bedrock을 사용하여 Amazon Nova Reel 1.1 비디오를 생성하기 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 포괄적인 프롬프트 가이드라인과 stdio 및 SSE 전송 방식을 모두 지원하는 비동기 비디오 생성 도구를 제공합니다.

"Buy Me A Coffee" "PayPal.me"

기능

비동기 비디오 생성: 비디오 생성 작업 시작, 모니터링 및 검색
다중 전송 방식: stdio, 서버 전송 이벤트(SSE) 및 HTTP 스트리밍 지원
포괄적인 프롬프트 가이드: AWS 문서를 기반으로 한 내장 가이드라인
Docker 지원: 모든 전송 방식을 위한 즉시 사용 가능한 Docker 컨테이너
AWS 통합: AWS Bedrock 및 S3와 완벽하게 통합

Related MCP server: AWS Knowledge Base Retrieval MCP Server

사용 가능한 도구

1. `start_async_invoke`

새로운 비디오 생성 작업을 시작합니다.

매개변수:

prompt (필수): 비디오 생성을 위한 텍스트 설명
duration_seconds (선택): 비디오 길이 (12-120초, 6의 배수, 기본값: 12)
fps (선택): 초당 프레임 수 (기본값: 24)
dimension (선택): 비디오 해상도 (기본값: "1280x720")
seed (선택): 재현 가능한 결과를 위한 무작위 시드
task_type (선택): 작업 유형 (기본값: "MULTI_SHOT_AUTOMATED")

반환값: job_id, invocation_arn 및 예상 비디오 URL을 포함한 작업 세부 정보.

2. `list_async_invokes`

현재 상태와 함께 추적 중인 모든 비디오 생성 작업을 나열합니다.

반환값: 상태별 개수와 개별 작업 세부 정보를 포함한 모든 작업 요약.

3. `get_async_invoke`

특정 비디오 생성 작업에 대한 자세한 정보를 가져옵니다.

매개변수:

identifier (필수): job_id 또는 invocation_arn 중 하나

반환값: 완료 시 비디오 URL을 포함한 상세 작업 정보.

4. `get_prompting_guide`

효과적인 비디오 생성을 위한 포괄적인 프롬프트 가이드라인을 가져옵니다.

반환값: 상세한 프롬프트 모범 사례, 예시 및 템플릿.

설치

사전 요구 사항

Python 3.8+
Bedrock 액세스 권한이 있는 AWS 계정
비디오 출력을 위한 S3 버킷
적절한 권한이 있는 AWS 자격 증명

로컬 설치

서버 파일을 복제하거나 다운로드합니다.
종속성을 설치합니다:

pip install -e .

Docker 설치

사전 빌드된 이미지 사용 (권장)

GitHub Container Registry에서 다중 아키텍처 이미지를 가져옵니다:

# STDIO version
docker pull ghcr.io/mirecekd/novareel-mcp:latest-stdio

# SSE version  
docker pull ghcr.io/mirecekd/novareel-mcp:latest-sse

# HTTP Streaming version
docker pull ghcr.io/mirecekd/novareel-mcp:latest-http

로컬에서 빌드

제공된 스크립트를 사용하여 컨테이너를 빌드합니다:

# Build all versions
./build-all.sh

# Or build individual versions
./build-stdio.sh    # STDIO version
./build-sse.sh      # SSE version
./build-http.sh     # HTTP Streaming version

또는 docker-compose를 사용합니다:

docker-compose up -d

또는 빠른 시작 스크립트를 사용합니다:

# Build all images
./start.sh build

# Build specific version
./start.sh build-stdio
./start.sh build-sse
./start.sh build-http

구성

환경 변수

AWS_ACCESS_KEY_ID: AWS 액세스 키 ID
AWS_SECRET_ACCESS_KEY: AWS 비밀 액세스 키
AWS_REGION: AWS 리전 (기본값: us-east-1)
S3_BUCKET: 비디오 출력을 위한 S3 버킷 이름

.env 파일 예시

docker-compose를 위한 .env 파일을 생성합니다:

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_REGION=us-east-1
S3_BUCKET=my-video-generation-bucket

사용법

MCP 클라이언트 통합 (Cline/Claude Desktop)

MCP 클라이언트 구성에 서버를 추가합니다:

Cline 구성

Cline MCP 설정에 추가합니다:

{
  "mcpServers": {
    "Nova Reel Video MCP": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mirecekd/novareel-mcp:latest-stdio",
        "--aws-access-key-id",
        "YOUR_AWS_ACCESS_KEY_ID",
        "--aws-secret-access-key",
        "YOUR_AWS_SECRET_ACCESS_KEY",
        "--s3-bucket",
        "YOUR_S3_BUCKET_NAME"
      ]
    }
  }
}

Claude Desktop 구성

Claude Desktop의 claude_desktop_config.json에 추가합니다:

{
  "mcpServers": {
    "novareel-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i", 
        "--rm",
        "ghcr.io/mirecekd/novareel-mcp:latest-stdio",
        "--aws-access-key-id",
        "YOUR_AWS_ACCESS_KEY_ID",
        "--aws-secret-access-key",
        "YOUR_AWS_SECRET_ACCESS_KEY",
        "--s3-bucket",
        "YOUR_S3_BUCKET_NAME"
      ]
    }
  }
}

대안: 로컬 Python 설치

Docker 없이 실행하려는 경우:

{
  "mcpServers": {
    "novareel-mcp": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/mirecekd/novareel-mcp.git",
        "novareel-mcp-server",
        "--aws-access-key-id", "YOUR_AWS_ACCESS_KEY_ID",
        "--aws-secret-access-key", "YOUR_AWS_SECRET_ACCESS_KEY",
        "--s3-bucket", "YOUR_S3_BUCKET_NAME"
      ]
    }
  }
}

중요: 자리 표시자 값을 실제 AWS 자격 증명 및 S3 버킷 이름으로 바꾸십시오.

uvx로 실행 (권장)

# First build the package
./build.sh

# Then run from wheel file
uvx --from ./dist/novareel_mcp-1.0.0-py3-none-any.whl novareel-mcp-server --aws-access-key-id YOUR_KEY --aws-secret-access-key YOUR_SECRET --s3-bucket YOUR_BUCKET

# Or from current directory during development (without build)
uvx --from . novareel-mcp-server --aws-access-key-id YOUR_KEY --aws-secret-access-key YOUR_SECRET --s3-bucket YOUR_BUCKET

# Or using start script
./start.sh build-package  # Build wheel

Stdio 버전 (직접 MCP 클라이언트)

# Local execution
python main.py --aws-access-key-id YOUR_KEY --aws-secret-access-key YOUR_SECRET --s3-bucket YOUR_BUCKET

# Docker execution
docker run --rm -i mirecekd/novareel-mcp-server:stdio --aws-access-key-id YOUR_KEY --aws-secret-access-key YOUR_SECRET --s3-bucket YOUR_BUCKET

SSE 버전 (웹 인터페이스)

# Local execution
python -m novareel_mcp_server.server_sse --aws-access-key-id YOUR_KEY --aws-secret-access-key YOUR_SECRET --s3-bucket YOUR_BUCKET --host 0.0.0.0 --port 8000

# Docker execution
docker run -p 8000:8000 -e AWS_ACCESS_KEY_ID=YOUR_KEY -e AWS_SECRET_ACCESS_KEY=YOUR_SECRET -e S3_BUCKET=YOUR_BUCKET mirecekd/novareel-mcp-server:sse

그런 다음 SSE 엔드포인트를 위해 http://localhost:8000/sse/에 접속합니다.

HTTP 스트리밍 버전 (양방향 전송)

# Local execution
python -m novareel_mcp_server.server_http --aws-access-key-id YOUR_KEY --aws-secret-access-key YOUR_SECRET --s3-bucket YOUR_BUCKET --host 0.0.0.0 --port 8001

# Docker execution
docker run -p 8001:8001 -e AWS_ACCESS_KEY_ID=YOUR_KEY -e AWS_SECRET_ACCESS_KEY=YOUR_SECRET -e S3_BUCKET=YOUR_BUCKET ghcr.io/mirecekd/novareel-mcp:latest-http

그런 다음 HTTP 스트리밍 전송을 위해 http://localhost:8001에 접속합니다.

패키지 빌드

배포 패키지를 생성하려면:

# Install build tools
pip install build

# Create package
python3 -m build

# Output files will be in dist/

사용 예시

기본 비디오 생성

# Start a video generation job
result = start_async_invoke(
    prompt="A majestic eagle soars over a mountain valley, camera tracking its flight as it circles above a pristine lake",
    duration_seconds=24,
    fps=24,
    dimension="1920x1080"
)

job_id = result["job_id"]
print(f"Started job: {job_id}")

# Check job status
status = get_async_invoke(job_id)
print(f"Status: {status['status']}")

# When completed, get video URL
if status["status"] == "Completed":
    print(f"Video URL: {status['video_url']}")

모든 작업 나열

# Get overview of all jobs
jobs = list_async_invokes()
print(f"Total jobs: {jobs['total_invocations']}")
print(f"Completed: {jobs['summary']['completed']}")
print(f"In progress: {jobs['summary']['in_progress']}")

프롬프트 가이드라인

이 서버에는 AWS 문서를 기반으로 한 포괄적인 프롬프트 가이드라인이 포함되어 있습니다. 다음을 사용하여 액세스하십시오:

guide = get_prompting_guide()

주요 프롬프트 팁

구체적으로 작성: 상세하고 묘사적인 언어를 사용하십시오.
- 좋음: "눈 덮인 소나무 가지에 앉아 있는 붉은 추기경, 나무 사이로 스며드는 아침 햇살"
- 나쁨: "나무 위의 새"
카메라 용어 사용: 샷 구도를 제어하십시오.
- "나무를 조각하는 손의 클로즈업 샷"
- "산 풍경을 보여주는 와이드 샷"
- "카메라가 계곡을 가로질러 왼쪽으로 팬(pan)함"
조명 세부 정보 포함: 분위기를 지정하십시오.
- "긴 그림자를 드리우는 골든 아워 조명"
- "부드러운 블루 아워 황혼"
- "머리 위의 극적인 폭풍 구름"
길이에 따른 구조화: 비디오 길이에 복잡성을 맞추십시오.
- 12-24초: 단일 동작 또는 순간
- 30-60초: 2-3개의 뚜렷한 동작
- 60-120초: 여러 장면이 포함된 전체 서사

카테고리별 프롬프트 예시

자연 (짧음 - 12초):

Close-up of morning dew drops on a spider web, with soft sunrise lighting creating rainbow reflections

도시 (중간 - 30초):

A street musician plays violin in a subway station, commuters pause to listen, coins drop into his case, camera slowly pulls back to reveal the bustling underground scene

인물 (길음 - 60초):

Portrait of a chef preparing a signature dish: selecting fresh ingredients at market, returning to kitchen, methodically preparing each component, plating with artistic precision, and presenting the finished masterpiece

AWS 권한

AWS 자격 증명에는 다음 권한이 필요합니다:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "bedrock:InvokeModel",
                "bedrock:StartAsyncInvoke",
                "bedrock:GetAsyncInvoke",
                "bedrock:ListFoundationModels"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::your-bucket-name",
                "arn:aws:s3:::your-bucket-name/*"
            ]
        }
    ]
}

비디오 출력

생성된 비디오는 S3 버킷에 다음 구조로 저장됩니다:

s3://your-bucket/
├── job-id-1/
│   └── output.mp4
├── job-id-2/
│   └── output.mp4
└── ...

비디오는 HTTPS URL을 통해 액세스할 수 있습니다:

https://your-bucket.s3.region.amazonaws.com/job-id/output.mp4

지원되는 비디오 사양

길이: 12-120초 (6의 배수여야 함)
프레임 속도: 24 fps (권장)
해상도:
- 1280x720 (HD)
형식: MP4
모델: amazon.nova-reel-v1:1

문제 해결

일반적인 문제

AWS 자격 증명 오류
- AWS 자격 증명이 올바른지 확인하십시오.
- 계정에 Bedrock 액세스 권한이 활성화되어 있는지 확인하십시오.
- IAM 권한을 확인하십시오.
S3 버킷 액세스
- 버킷이 존재하고 액세스 가능한지 확인하십시오.
- 버킷 권한을 확인하십시오.
- 버킷이 Bedrock과 동일한 리전에 있는지 확인하십시오.
길이 유효성 검사
- 길이는 12-120초여야 합니다.
- 6의 배수여야 합니다.
- 유효한 값: 12, 18, 24, 30, 36, 42, 48, 54, 60, 66, 72, 78, 84, 90, 96, 102, 108, 114, 120
작업을 찾을 수 없음
- list_async_invokes를 사용하여 추적 중인 모든 작업을 확인하십시오.
- 작업은 메모리에 저장되며 서버 재시작 시 손실됩니다.
- 프로덕션 환경의 경우 영구 저장소를 구현하십시오.

디버그 모드

환경 변수를 설정하여 디버그 로깅을 활성화하십시오:

export PYTHONUNBUFFERED=1

개발

프로젝트 구조

novareel-mcp-server/
├── main.py              # Main MCP server (stdio)
├── main_sse.py          # SSE version of MCP server
├── main_http.py         # HTTP Streaming version of MCP server
├── prompting_guide.py   # AWS prompting guidelines
├── pyproject.toml       # Python dependencies
├── Dockerfile.stdio     # Docker for stdio version
├── Dockerfile.sse       # Docker for SSE version
├── Dockerfile.http      # Docker for HTTP streaming version
├── docker-compose.yml   # Container orchestration
└── README.md           # This documentation

기여 방법

저장소를 포크(Fork)합니다.
기능 브랜치를 생성합니다.
변경 사항을 적용합니다.
모든 전송 버전(stdio, SSE, HTTP 스트리밍)으로 테스트합니다.
풀 리퀘스트(Pull Request)를 제출합니다.

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하십시오.

지원

문제 및 질문 사항:

문제 해결 섹션을 확인하십시오.
AWS Bedrock 문서를 검토하십시오.
저장소에 이슈를 제기하십시오.