playbooks
Learn Cursor Rules Windsurf Rules CLAUDE.md AGENTS.md
Rules Builder MCPs Modes
Log in

Amazon Nova Reel MCP server

Integrates with Amazon Nova Reel 1.1 through AWS Bedrock to generate videos from text prompts with configurable duration, frame rate, and dimensions, including job tracking, S3 storage, and detailed prompting guidelines for camera control and narrative structure.
Back to servers
Setup instructions
Provider
mirecekd
Release date
Jun 24, 2025
Stats
1 star
View Markdown
View on GitHub

Amazon Nova Reel 1.1 MCP Server provides a Model Context Protocol (MCP) server for video generation using AWS Bedrock. It supports asynchronous video generation with comprehensive prompting guidelines and multiple transport methods including stdio and SSE.

Installation

Prerequisites

  • Python 3.8+
  • AWS Account with Bedrock access
  • S3 bucket for video output
  • AWS credentials with appropriate permissions

Local Installation

Install dependencies:

pip install -e .

Docker Installation

Using Pre-built Images (Recommended)

Pull multi-architecture images from 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

Building Locally

Build containers using provided scripts:

# 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

Or use docker-compose:

docker-compose up -d

Or use the quick start script:

# Build all images
./start.sh build

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

Configuration

Environment Variables

  • AWS_ACCESS_KEY_ID: Your AWS access key ID
  • AWS_SECRET_ACCESS_KEY: Your AWS secret access key
  • AWS_REGION: AWS region (default: us-east-1)
  • S3_BUCKET: S3 bucket name for video output

.env File Example

Create a .env file for 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

Usage

MCP Client Integration (Cline/Claude Desktop)

Add the server to your MCP client configuration:

Cline Configuration

Add to your Cline MCP settings:

{
  "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 Configuration

Add to your 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"
      ]
    }
  }
}

Alternative: Local Python Installation

If you prefer running without 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"
      ]
    }
  }
}

Important: Replace the placeholder values with your actual AWS credentials and S3 bucket name.

Running with uvx (Recommended)

# 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

Stdio Version (Direct MCP Client)

# 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 Version (Web Interface)

# 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

Then access http://localhost:8000/sse/ for the SSE endpoint.

HTTP Streaming Version (Bidirectional Transport)

# 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

Then access http://localhost:8001 for the HTTP streaming transport.

Available Tools

1. start_async_invoke

Start a new video generation job.

Parameters:

  • prompt (required): Text description for video generation
  • duration_seconds (optional): Video duration (12-120 seconds, multiples of 6, default: 12)
  • fps (optional): Frames per second (default: 24)
  • dimension (optional): Video dimensions (default: "1280x720")
  • seed (optional): Random seed for reproducible results
  • task_type (optional): Task type (default: "MULTI_SHOT_AUTOMATED")

Returns: Job details including job_id, invocation_arn, and estimated video URL.

2. list_async_invokes

List all tracked video generation jobs with their current status.

Returns: Summary of all jobs with status counts and individual job details.

3. get_async_invoke

Get detailed information about a specific video generation job.

Parameters:

  • identifier (required): Either job_id or invocation_arn

Returns: Detailed job information including video URL when completed.

4. get_prompting_guide

Get comprehensive prompting guidelines for effective video generation.

Returns: Detailed prompting best practices, examples, and templates.

Example Usage

Basic Video Generation

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

List All Jobs

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

Prompting Guidelines

Key Prompting Tips

  1. Be Specific: Use detailed, descriptive language

    • Good: "A red cardinal perched on a snow-covered pine branch, morning sunlight filtering through the trees"
    • Bad: "A bird on a tree"

  2. Use Camera Terminology: Control shot composition

    • "Close-up shot of hands carving wood"
    • "Wide shot establishing the mountain landscape"
    • "Camera pans left across the valley"

  3. Include Lighting Details: Specify atmosphere

    • "Golden hour lighting casting long shadows"
    • "Soft blue hour twilight"
    • "Dramatic storm clouds overhead"

  4. Structure for Duration: Match complexity to video length

    • 12-24 seconds: Single action or moment
    • 30-60 seconds: 2-3 distinct actions
    • 60-120 seconds: Full narrative with multiple scenes

Example Prompts by Category

Nature (Short - 12s):

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

Urban (Medium - 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

Portrait (Long - 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

Supported Video Specifications

  • Duration: 12-120 seconds (must be multiples of 6)
  • Frame Rate: 24 fps (recommended)
  • Dimensions: 1280x720 (HD)
  • Format: MP4
  • Model: amazon.nova-reel-v1:1

Troubleshooting

Common Issues

  1. AWS Credentials Error

    • Verify your AWS credentials are correct
    • Ensure your account has Bedrock access enabled
    • Check IAM permissions

  2. S3 Bucket Access

    • Verify bucket exists and is accessible
    • Check bucket permissions
    • Ensure bucket is in the same region as Bedrock

  3. Duration Validation

    • Duration must be 12-120 seconds
    • Must be a multiple of 6
    • Valid values: 12, 18, 24, 30, 36, 42, 48, 54, 60, 66, 72, 78, 84, 90, 96, 102, 108, 114, 120

  4. Job Not Found

    • Use list_async_invokes to see all tracked jobs
    • Jobs are stored in memory and lost on server restart

Debug Mode

Enable debug logging by setting environment variable:

export PYTHONUNBUFFERED=1

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later