Novareel 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 完全集成。

📦 安装指南

前提条件

• Python 3.8 及以上版本
• 具备 Bedrock 访问权限的 AWS 账户
• 用于存储视频输出的 S3 存储桶
• 拥有适当权限的 AWS 凭证

本地安装

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

pip install -e .

Docker 安装

使用预构建镜像（推荐）

从 GitHub 容器注册表拉取多架构镜像：

# STDIO 版本
docker pull ghcr.io/mirecekd/novareel-mcp:latest-stdio

# SSE 版本  
docker pull ghcr.io/mirecekd/novareel-mcp:latest-sse

# HTTP 流版本
docker pull ghcr.io/mirecekd/novareel-mcp:latest-http

本地构建

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

# 构建所有版本
./build-all.sh

# 或者构建单个版本
./build-stdio.sh    # STDIO 版本
./build-sse.sh      # SSE 版本
./build-http.sh     # HTTP 流版本

2. 或者使用 Docker Compose：

docker-compose up -d

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

# 构建所有镜像
./start.sh build

# 构建特定版本
./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 运行（推荐）

# 首先构建包
./build.sh

# 然后从 wheel 文件运行
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

# 或者在开发期间从当前目录运行（无需构建）
uvx --from . novareel-mcp-server --aws-access-key-id YOUR_KEY --aws-secret-access-key YOUR_SECRET --s3-bucket YOUR_BUCKET

# 或者使用启动脚本
./start.sh build-package  # 构建 wheel

STDIO 版本（直接 MCP 客户端）

# 本地执行
python main.py --aws-access-key-id YOUR_KEY --aws-secret-access-key YOUR_SECRET --s3-bucket YOUR_BUCKET

# Docker 执行
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 界面）

# 本地执行
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 执行
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 流版本（双向传输）

# 本地执行
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 执行
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 流传输。

包构建

要创建分发包：

# 安装构建工具
pip install build

# 创建包
python3 -m build

# 输出文件将位于 dist/ 目录中

基础用法

# 启动一个视频生成任务
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}")

# 检查任务状态
status = get_async_invoke(job_id)
print(f"Status: {status['status']}")

# 任务完成后，获取视频 URL
if status["status"] == "Completed":
    print(f"Video URL: {status['video_url']}")

列出所有任务

# 获取所有任务的概述
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']}")

📚 详细文档

可用工具

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

获取用于有效视频生成的全面提示指南。

返回值：详细的提示最佳实践、示例和模板。

提示指南

该服务器包含基于 AWS 文档的全面提示指南。可使用以下代码访问：

guide = get_prompting_guide()

关键提示技巧

1. 具体描述：使用详细、描述性的语言。
   • 好的示例："A red cardinal perched on a snow-covered pine branch, morning sunlight filtering through the trees"
   • 不好的示例："A bird on a tree"
2. 使用相机术语：控制镜头组成。
   • "Close-up shot of hands carving wood"
   • "Wide shot establishing the mountain landscape"
   • "Camera pans left across the valley"
3. 包含照明细节：指定氛围。
   • "Golden hour lighting casting long shadows"
   • "Soft blue hour twilight"
   • "Dramatic storm clouds overhead"
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              # 主 MCP 服务器（stdio）
├── main_sse.py          # MCP 服务器的 SSE 版本
├── main_http.py         # MCP 服务器的 HTTP 流版本
├── prompting_guide.py   # AWS 提示指南
├── pyproject.toml       # Python 依赖项
├── Dockerfile.stdio     # STDIO 版本的 Docker 文件
├── Dockerfile.sse       # SSE 版本的 Docker 文件
├── Dockerfile.http      # HTTP 流版本的 Docker 文件
├── docker-compose.yml   # 容器编排
└── README.md           # 本文档

贡献

1. 分叉仓库。
2. 创建功能分支。
3. 进行更改。
4. 使用所有传输版本（stdio、SSE、HTTP 流）进行测试。
5. 提交拉取请求。

📄 许可证

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

支持

如有问题和疑问：

1. 查看故障排除部分。
2. 查阅 AWS Bedrock 文档。
3. 在仓库中创建一个问题。

相关链接

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