Amazon Nova Reel 1.1

Un servidor MCP para generar videos usando Amazon Nova Reel 1.1 a través de AWS Bedrock.

Documentación

Servidor MCP de Amazon Nova Reel 1.1

Un servidor de Protocolo de Contexto de Modelo (MCP) para la generación de videos con Amazon Nova Reel 1.1 usando AWS Bedrock. Este servidor proporciona herramientas para la generación asíncrona de videos con guías completas de indicaciones y soporte para transporte stdio y SSE.

Características

Generación de Video Asíncrona: Inicia, monitorea y recupera trabajos de generación de video
Múltiples Métodos de Transporte: Soporte para stdio, Eventos Enviados por el Servidor (SSE) y Transmisión HTTP
Guía Integral de Indicaciones: Pautas integradas basadas en la documentación de AWS
Soporte Docker: Contenedores Docker listos para usar para todos los métodos de transporte
Integración con AWS: Integración completa con AWS Bedrock y S3

Herramientas Disponibles

1. `start_async_invoke`

Inicia un nuevo trabajo de generación de video.

Parámetros:

prompt (obligatorio): Descripción de texto para la generación de video
duration_seconds (opcional): Duración del video (12-120 segundos, múltiplos de 6, predeterminado: 12)
fps (opcional): Fotogramas por segundo (predeterminado: 24)
dimension (opcional): Dimensiones del video (predeterminado: "1280x720")
seed (opcional): Semilla aleatoria para resultados reproducibles
task_type (opcional): Tipo de tarea (predeterminado: "MULTI_SHOT_AUTOMATED")

Devuelve: Detalles del trabajo, incluidos job_id, invocation_arn y la URL estimada del video.

2. `list_async_invokes`

Lista todos los trabajos de generación de video rastreados con su estado actual.

Devuelve: Resumen de todos los trabajos con conteos de estado y detalles individuales de cada trabajo.

3. `get_async_invoke`

Obtiene información detallada sobre un trabajo específico de generación de video.

Parámetros:

identifier (obligatorio): Ya sea job_id o invocation_arn

Devuelve: Información detallada del trabajo, incluida la URL del video cuando se completa.

4. `get_prompting_guide`

Obtiene guías integrales de indicaciones para una generación de video efectiva.

Devuelve: Mejores prácticas detalladas de indicaciones, ejemplos y plantillas.

Instalación

Requisitos Previos

Python 3.8+
Cuenta de AWS con acceso a Bedrock
Bucket de S3 para la salida de video
Credenciales de AWS con permisos apropiados

Instalación Local

Clona o descarga los archivos del servidor
Instala las dependencias:

pip install -e .

Instalación con Docker

Usando Imágenes Preconstruidas (Recomendado)

Extrae imágenes multiarquitectura del Registro de Contenedores de GitHub:

# 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

Construcción Local

Construye los contenedores usando los scripts proporcionados:

# 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

O usa docker-compose:

docker-compose up -d

O usa el script de inicio rápido:

# Build all images
./start.sh build

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

Configuración

Variables de Entorno

AWS_ACCESS_KEY_ID: Tu ID de clave de acceso de AWS
AWS_SECRET_ACCESS_KEY: Tu clave de acceso secreta de AWS
AWS_REGION: Región de AWS (predeterminado: us-east-1)
S3_BUCKET: Nombre del bucket de S3 para la salida de video

Ejemplo de Archivo .env

Crea un archivo .env para docker-compose:

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

Uso

Integración con Cliente MCP (Cline/Claude Desktop)

Agrega el servidor a tu configuración de cliente MCP:

Configuración de Cline

Agrega a tu configuración de MCP de Cline:

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

Configuración de Claude Desktop

Agrega a tu claude_desktop_config.json de Claude Desktop:

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

Alternativa: Instalación Local de Python

Si prefieres ejecutar sin 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"
      ]
    }
  }
}

Importante: Reemplaza los valores de marcador de posición con tus credenciales reales de AWS y el nombre de tu bucket de S3.

Ejecución con uvx (Recomendado)

# 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

Versión Stdio (Cliente MCP Directo)

# 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

Versión SSE (Interfaz Web)

# 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

Luego accede a http://localhost:8000/sse/ para el endpoint SSE.

Versión de Transmisión HTTP (Transporte Bidireccional)

# 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

Luego accede a http://localhost:8001 para el transporte de transmisión HTTP.

Compilación del Paquete

Para crear un paquete de distribución:

# Install build tools
pip install build

# Create package
python3 -m build

# Output files will be in dist/

Ejemplo de Uso

Generación Básica de Video

# 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']}")

Listar Todos los Trabajos

# 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']}")

Guías de Indicaciones

El servidor incluye guías integrales de indicaciones basadas en la documentación de AWS. Accede a ellas usando:

guide = get_prompting_guide()

Consejos Clave para Indicaciones

Sé Específico: Usa lenguaje detallado y descriptivo
- Bueno: "Un cardenal rojo posado en una rama de pino cubierta de nieve, luz matutina filtrándose entre los árboles"
- Malo: "Un pájaro en un árbol"
Usa Terminología de Cámara: Controla la composición de la toma
- "Toma en primer plano de manos tallando madera"
- "Toma amplia que establece el paisaje montañoso"
- "La cámara hace paneo a la izquierda a través del valle"
Incluye Detalles de Iluminación: Especifica la atmósfera
- "Iluminación de la hora dorada proyectando sombras largas"
- "Crepúsculo suave de la hora azul"
- "Nubes de tormenta dramáticas en lo alto"
Estructura para la Duración: Haz coincidir la complejidad con la longitud del video
- 12-24 segundos: Una sola acción o momento
- 30-60 segundos: 2-3 acciones distintas
- 60-120 segundos: Narrativa completa con múltiples escenas

Ejemplos de Indicaciones por Categoría

Naturaleza (Corta - 12s):

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

Urbano (Media - 30s):

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

Retrato (Larga - 60s):

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

Permisos de AWS

Tus credenciales de AWS necesitan los siguientes permisos:

{
    "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/*"
            ]
        }
    ]
}

Salida de Video

Los videos generados se almacenan en tu bucket de S3 con la siguiente estructura:

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

Los videos son accesibles mediante URLs HTTPS:

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

Especificaciones de Video Soportadas

Duración: 12-120 segundos (deben ser múltiplos de 6)
Fotogramas por Segundo: 24 fps (recomendado)
Dimensiones:
- 1280x720 (HD)
Formato: MP4
Modelo: amazon.nova-reel-v1:1

Solución de Problemas

Problemas Comunes

Error de Credenciales de AWS
- Verifica que tus credenciales de AWS sean correctas
- Asegúrate de que tu cuenta tenga habilitado el acceso a Bedrock
- Revisa los permisos de IAM
Acceso al Bucket de S3
- Verifica que el bucket exista y sea accesible
- Revisa los permisos del bucket
- Asegúrate de que el bucket esté en la misma región que Bedrock
Validación de Duración
- La duración debe ser de 12-120 segundos
- Debe ser un múltiplo de 6
- Valores válidos: 12, 18, 24, 30, 36, 42, 48, 54, 60, 66, 72, 78, 84, 90, 96, 102, 108, 114, 120
Trabajo No Encontrado
- Usa list_async_invokes para ver todos los trabajos rastreados
- Los trabajos se almacenan en memoria y se pierden al reiniciar el servidor
- Para producción, implementa almacenamiento persistente

Modo de Depuración

Habilita el registro de depuración configurando la variable de entorno:

export PYTHONUNBUFFERED=1

Desarrollo

Estructura del Proyecto

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

Contribuciones

Haz un fork del repositorio
Crea una rama de características
Realiza tus cambios
Prueba con todas las versiones de transporte (stdio, SSE, transmisión HTTP)
Envía una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENSE para más detalles.

Soporte

Para problemas y preguntas:

Consulta la sección de solución de problemas
Revisa la documentación de AWS Bedrock
Abre un problema en el repositorio