Servidor MCP de Amazon Nova Reel 1.1

Un servidor del Protocolo de Contexto de Modelo (MCP) para la generación de vídeo con Amazon Nova Reel 1.1 utilizando AWS Bedrock. Este servidor proporciona herramientas para la generación de vídeo asíncrona con directrices de prompts completas y soporte para transporte tanto stdio como SSE.

Características

• Generación de vídeo asíncrona: Inicie, supervise y recupere trabajos de generación de vídeo

• Múltiples métodos de transporte: Soporte para stdio, Server-Sent Events (SSE) y HTTP Streaming

• Guía completa de prompts: Directrices integradas basadas en la documentación de AWS

• Soporte para 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

Related MCP server: AWS Knowledge Base Retrieval MCP Server

Herramientas disponibles

1. start_async_invoke

Inicia un nuevo trabajo de generación de vídeo.

Parámetros:

• prompt (obligatorio): Descripción textual para la generación del vídeo

• duration_seconds (opcional): Duración del vídeo (12-120 segundos, múltiplos de 6, predeterminado: 12)

• fps (opcional): Fotogramas por segundo (predeterminado: 24)

• dimension (opcional): Dimensiones del vídeo (predeterminado: "1280x720")

• seed (opcional): Semilla aleatoria para resultados reproducibles

• task_type (opcional): Tipo de tarea (predeterminado: "MULTI_SHOT_AUTOMATED")

Retorna: Detalles del trabajo, incluyendo job_id, invocation_arn y la URL estimada del vídeo.

2. list_async_invokes

Enumera todos los trabajos de generación de vídeo rastreados con su estado actual.

Retorna: Resumen de todos los trabajos con recuentos de estado y detalles individuales de cada trabajo.

3. get_async_invoke

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

Parámetros:

• identifier (obligatorio): Ya sea job_id o invocation_arn

Retorna: Información detallada del trabajo, incluyendo la URL del vídeo cuando se completa.

4. get_prompting_guide

Obtiene directrices completas de prompts para una generación de vídeo efectiva.

Retorna: Mejores prácticas, ejemplos y plantillas detalladas para prompts.

Instalación

Requisitos previos

• Python 3.8+

• Cuenta de AWS con acceso a Bedrock

• Bucket de S3 para la salida de vídeo

• Credenciales de AWS con los permisos adecuados

Instalación local

1. Clone o descargue los archivos del servidor

2. Instale las dependencias:

pip install -e .

Instalación con Docker

Uso de imágenes preconstruidas (Recomendado)

Extraiga 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

1. Construya 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

2. O utilice docker-compose:

docker-compose up -d

3. O utilice 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: Su ID de clave de acceso de AWS

• AWS_SECRET_ACCESS_KEY: Su 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 vídeo

Ejemplo de archivo .env

Cree 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)

Añada el servidor a la configuración de su cliente MCP:

Configuración de Cline

Añada a sus ajustes de 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"
      ]
    }
  }
}

Configuración de Claude Desktop

Añada a su 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 prefiere 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: Reemplace los valores de marcador de posición con sus credenciales reales de AWS y el nombre de su 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 acceda a http://localhost:8000/sse/ para el endpoint SSE.

Versión HTTP Streaming (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 acceda a http://localhost:8001 para el transporte de streaming HTTP.

Construcció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 vídeo

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

Directrices de prompts

El servidor incluye directrices completas de prompts basadas en la documentación de AWS. Acceda a ellas usando:

guide = get_prompting_guide()

Consejos clave para prompts

1. Sea específico: Use un lenguaje detallado y descriptivo

   • Bueno: "Un cardenal rojo posado en una rama de pino cubierta de nieve, la luz del sol de la mañana filtrándose a través de los árboles"

   • Malo: "Un pájaro en un árbol"

2. Use terminología de cámara: Controle la composición de la toma

   • "Primer plano de manos tallando madera"

   • "Plano general estableciendo el paisaje montañoso"

   • "La cámara hace un paneo a la izquierda a través del valle"

3. Incluya detalles de iluminación: Especifique la atmósfera

   • "Iluminación de la hora dorada proyectando sombras largas"

   • "Suave crepúsculo de la hora azul"

   • "Nubes de tormenta dramáticas sobre la cabeza"

4. Estructure según la duración: Ajuste la complejidad a la duración del vídeo

   • 12-24 segundos: Acción o momento único

   • 30-60 segundos: 2-3 acciones distintas

   • 60-120 segundos: Narrativa completa con múltiples escenas

Ejemplos de prompts por categoría

Naturaleza (Corto - 12s):

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

Urbano (Medio - 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 (Largo - 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

Sus 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 vídeo

Los vídeos generados se almacenan en su bucket de S3 con la siguiente estructura:

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

Los vídeos son accesibles a través de URLs HTTPS:

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

Especificaciones de vídeo soportadas

• Duración: 12-120 segundos (deben ser múltiplos de 6)

• Velocidad de fotogramas: 24 fps (recomendado)

• Dimensiones:

  • 1280x720 (HD)

• Formato: MP4

• Modelo: amazon.nova-reel-v1:1

Solución de problemas

Problemas comunes

1. Error de credenciales de AWS

   • Verifique que sus credenciales de AWS sean correctas

   • Asegúrese de que su cuenta tenga habilitado el acceso a Bedrock

   • Compruebe los permisos de IAM

2. Acceso al bucket de S3

   • Verifique que el bucket exista y sea accesible

   • Compruebe los permisos del bucket

   • Asegúrese de que el bucket esté en la misma región que Bedrock

3. 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

4. Trabajo no encontrado

   • Use 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, implemente almacenamiento persistente

Modo de depuración

Habilite 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

Contribución

1. Haga un fork del repositorio

2. Cree una rama de características

3. Realice sus cambios

4. Pruebe con todas las versiones de transporte (stdio, SSE, HTTP streaming)

5. Envíe una solicitud de extracción (pull request)

Licencia

Este proyecto está bajo la Licencia MIT - consulte el archivo LICENSE para obtener más detalles.

Soporte

Para problemas y preguntas:

1. Consulte la sección de solución de problemas

2. Revise la documentación de AWS Bedrock

3. Abra un issue en el repositorio

Enlaces relacionados

• Documentación de AWS Nova Reel

• Guía de prompts para generación de vídeo

• Prompts para control de cámara

• Protocolo de Contexto de Modelo

• Framework FastMCP