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 框架