novareel-mcp

MCP server to generate video with Amazon Nova Reel

1 stars PythonOthers Updated Apr 24, 2026

Documentation

Amazon Nova Reel 1.1 MCP Server

A Model Context Protocol (MCP) server for Amazon Nova Reel 1.1 video generation using AWS Bedrock. This server provides tools for asynchronous video generation with comprehensive prompting guidelines and both stdio and SSE transport support.

Features

Asynchronous Video Generation: Start, monitor, and retrieve video generation jobs
Multiple Transport Methods: Support for stdio, Server-Sent Events (SSE), and HTTP Streaming
Comprehensive Prompting Guide: Built-in guidelines based on AWS documentation
Docker Support: Ready-to-use Docker containers for all transport methods
AWS Integration: Full integration with AWS Bedrock and S3

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.

Installation

Prerequisites

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

Local Installation

1. Clone or download the server files

2. Install dependencies:

bash

pip install -e .

Docker Installation

Using Pre-built Images (Recommended)

Pull multi-architecture images from GitHub Container Registry:

bash

# 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

1. Build containers using provided scripts:

bash

# 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. Or use docker-compose:

bash

docker-compose up -d

3. Or use the quick start script:

bash

# 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:

env

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:

json

{
  "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`:

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:

json

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

bash

# 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 Version (Direct MCP Client)

bash

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

bash

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

bash

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

Package Build

To create a distribution package:

bash

# Install build tools
pip install build

# Create package
python3 -m build

# Output files will be in dist/

Example Usage

Basic Video Generation

python

# 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

python

# 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

The server includes comprehensive prompting guidelines based on AWS documentation. Access them using:

python

guide = get_prompting_guide()

Key Prompting Tips

1. Be Specific: Use detailed, descriptive language

2. Use Camera Terminology: Control shot composition

3. Include Lighting Details: Specify atmosphere

4. Structure for Duration: Match complexity to video length

Example Prompts by Category

Nature (Short - 12s):

code

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

Urban (Medium - 30s):

code

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

code

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 Permissions

Your AWS credentials need the following permissions:

json

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

Video Output

Generated videos are stored in your S3 bucket with the following structure:

code

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

Videos are accessible via HTTPS URLs:

code

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

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

2. S3 Bucket Access

3. Duration Validation

4. Job Not Found

Debug Mode

Enable debug logging by setting environment variable:

bash

export PYTHONUNBUFFERED=1

Development

Project Structure

code

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

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Test with all transport versions (stdio, SSE, HTTP streaming)

5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

1. Check the troubleshooting section

2. Review AWS Bedrock documentation

3. Open an issue in the repository

Frequently asked questions

What is novareel-mcp?

novareel-mcp is MCP server to generate video with Amazon Nova Reel

How do I install novareel-mcp?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is novareel-mcp open source?

Yes — it is hosted on GitHub at https://github.com/mirecekd/novareel-mcp and has 1 stars.

Related MCP tools

cognee

Cognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.

30,433 Python

agent-memoryagent-skillsai+16

skyvern

Automate browser based workflows with AI

22,930 Python

apiautomationbrowser+13

hindsight

Hindsight: Agent Memory That Learns

22,468 Python

agentic-aimemoryagents+1

watermarks-remover

A privacy-first app that strips AI watermarks from content you own.

20,504 Python

agent-skillaic2pa+12

Qwen-Agent

Agent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.

17,062 Python

pal-mcp-server

The power of Claude Code / GeminiCLI / CodexCLI + [Gemini / OpenAI / OpenRouter / Azure / Grok / Ollama / Custom Model / All Of The Above] working as one.

11,731 Python

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP

Documentation

Amazon Nova Reel 1.1 MCP Server

Features

Available Tools

1. `start_async_invoke`

2. `list_async_invokes`

3. `get_async_invoke`

4. `get_prompting_guide`

Installation

Prerequisites

Local Installation

Docker Installation

Using Pre-built Images (Recommended)

Building Locally

Configuration

Environment Variables

.env File Example

Usage

MCP Client Integration (Cline/Claude Desktop)

Cline Configuration

Claude Desktop Configuration

Alternative: Local Python Installation

Running with uvx (Recommended)

Stdio Version (Direct MCP Client)

SSE Version (Web Interface)

HTTP Streaming Version (Bidirectional Transport)

Package Build

Example Usage

Basic Video Generation

List All Jobs

Prompting Guidelines

Key Prompting Tips

Example Prompts by Category

AWS Permissions

Video Output

Supported Video Specifications

Troubleshooting

Common Issues

Debug Mode

Development

Project Structure

Contributing

License

Support

Related Links

Frequently asked questions

What is novareel-mcp?

How do I install novareel-mcp?

Is novareel-mcp open source?

Related MCP tools