Nova Reel Video Mcp

Amazon Nova Reel 1.1 MCP 服务

一个使用 AWS Bedrock 进行 Amazon Nova Reel 1.1 视频生成的模型上下文协议（MCP）服务。此服务提供异步视频生成工具，包含全面的提示词编写指南，并支持 stdio 和 SSE 传输方式。

功能

• 异步视频生成：启动、监控和获取视频生成任务
• 多种传输方式：支持 stdio、服务器发送事件（SSE）和 HTTP 流式传输
• 全面的提示词指南：内置基于 AWS 文档的指南
• Docker 支持：为所有传输方式提供可直接使用的 Docker 容器
• AWS 集成：与 AWS Bedrock 和 S3 完全集成

可用工具

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 凭证

本地安装

1. 克隆或下载服务文件
2. 安装依赖项：

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

本地构建

1. 使用提供的脚本构建容器：

# 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. 或使用 docker-compose：

docker-compose up -d

3. 或使用快速启动脚本：

# 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 版本（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

然后访问 http://localhost:8000/sse/ 以使用 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://localhost:8001 以使用 HTTP 流式传输。

构建软件包

创建分发包：

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

提示词要点

1. 具体明确：使用详细、描述性语言

   • 好的示例：“一只红色的北美红雀栖息在覆雪的松枝上，晨光透过树林洒落”
   • 不好的示例：“一只鸟在树上”

2. 使用摄影术语：控制镜头构图

   • “双手雕刻木头的特写镜头”
   • “展现山地景观的全景镜头”
   • “摄像机向左摇摄，扫过山谷”

3. 提供光线细节：明确氛围

   • “黄金时段的光线投下长长的影子”
   • “柔和的蓝调时刻暮光”
   • “头顶乌云翻涌，气氛戏剧化”

4. 根据时长组织内容：让复杂度与视频时长相匹配

   • 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

故障排除

常见问题

1. AWS 凭证错误

   • 确认 AWS 凭证正确
   • 确保账户已启用 Bedrock 访问权限
   • 检查 IAM 权限

2. S3 存储桶访问

   • 确认存储桶存在且可访问
   • 检查存储桶权限
   • 确保存储桶与 Bedrock 位于同一区域

3. 时长验证

   • 时长必须为 12-120 秒
   • 必须为 6 的倍数
   • 有效值：12、18、24、30、36、42、48、54、60、66、72、78、84、90、96、102、108、114、120

4. 未找到任务

   • 使用 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

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 使用所有传输版本（stdio、SSE、HTTP streaming）进行测试
5. 提交 pull request

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

支持

如有问题或疑问：

1. 查看故障排除部分
2. 阅读 AWS Bedrock 文档
3. 在仓库中提交 issue

相关链接

• AWS Nova Reel 文档
• 视频生成提示词指南
• 摄像机控制提示词
• 模型上下文协议
• FastMCP 框架