演示记录器MCP

MCP（模型上下文协议）服务器，使AI代理能够创建具有同步画外音旁白的专业演示视频。使用 任何网站或网络应用程序.

示例：你能创造什么

![Kagenti + MLflow Demo](https://www.youtube.com/watch?v=ns8jh_38fRA)

在YouTube上观看完整演示→

这个7分钟的演示完全是由一个使用该工具的AI代理创建的。它展示了在Kagenti上部署具有MLflow集成的自定义代理，包括：

浏览用户界面和填写表单
部署自定义容器映像
配置环境变量和端口
通过聊天测试部署的代理
探索工作流指标和跟踪

______________________________________________________________________

特性

屏幕录制 -以每秒30帧的速度捕获浏览器窗口
文本转语音 -使用OpenAI TTS（带API键）或Edge TTS（免费）生成画外音
音频视频同步 -调整视频速度以匹配旁白长度（保留所有内容）
基于场景的工作流 -内置指南强制执行简短、可管理的录制
多种模式 -主机（推荐质量）、容器（独立）

两种访问模式

模式	最适合	浏览器自动化	质量
主机模式	制作演示，原生屏幕质量	剧作家MCP（单独）	最佳 -本地分辨率
集装箱模式	快速设置，CI/CD，可复制构建	剧作家（包括在内）	良好-虚拟显示

______________________________________________________________________

快速入门：主机模式（推荐）

主机模式提供 最佳视频质量 通过捕获您的原生屏幕。这是创建专业演示的推荐设置。

先决条件

Python 3.10+ -用于演示录音机mcp
Node.js 18+ -剧作家MCP(npx 命令）
FFmpeg -用于视频处理(brew install ffmpeg 在macOS上）
铬 -Playwright的推荐浏览器

步骤1：安装演示记录器

git clone https://github.com/Schimuneck/demo-recorder-mcp.git
cd demo-recorder-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"

步骤2：配置光标MCP

添加到 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--browser=chrome",
        "--isolated"
      ]
    },
    "demo-recorder-local": {
      "command": "/path/to/demo-recorder-mcp/.venv/bin/recorder",
      "env": {
        "OPENAI_API_KEY": "sk-your-openai-key",
        "RECORDINGS_DIR": "${workspaceFolder}/recordings"
      }
    }
  }
}

重要提示： 替换 /path/to/demo-recorder-mcp 使用您的实际安装路径。

步骤3：禁用光标浏览器自动化（严重！）

⚠️ 此步骤是必需的 以避免视口溢出和窗口检测问题。

打开光标设置：

- macOS： Cmd + , - Windows/Linux： Ctrl + ,

在左侧边栏中，单击 “工具”
查找 “浏览器” 部分
集 “浏览器自动化” 到关
（可选）也禁用 “在浏览器中显示本地主机链接”

为什么这是必要的？ Cursor的内置浏览器自动化使用嵌入式浏览器窗口，该窗口：

存在视口大小问题（视口大于屏幕，导致溢出）
记录器难以正确识别和捕获
当两者都启用时，与Playwright MCP发生冲突
在录制过程中导致窗口标题检测问题

通过禁用它并使用Playwright MCP，您将获得一个独立的Chrome窗口，该窗口：

具有适当的视口大小
易于通过窗口标题识别（“谷歌Chrome”）
与屏幕记录器可靠配合使用
支持 --isolated 干净浏览器会话标志

步骤4:macOS屏幕录制权限

在macOS上，您必须授予屏幕录制权限：

首选 系统设置→ 隐私和安全→ 屏幕录制
添加光标到允许的列表
重新启动游标 授予许可后

步骤5：验证设置

重新启动Cursor后，测试设置：

询问光标： *“列出可用窗口”* → 应该没有错误地工作
询问光标： *“导航到https://example.com"* → Chrome应该打开
询问光标： *“拍摄浏览器快照”* → 应显示页面结构

您已经准备好创建演示了！

______________________________________________________________________

快速入门：容器模式

容器模式包含所有36个工具（14个演示录音机+22个剧作家）。最适合CI/CD或需要可复制环境时使用。

构建容器

git clone https://github.com/Schimuneck/demo-recorder-mcp.git
cd demo-recorder-mcp
podman build -t demo-recorder-mcp .  # or: docker build -t demo-recorder-mcp .

配置光标MCP

添加到 ~/.cursor/mcp.json:

对于Podman（macOS/Linux）：

{
  "mcpServers": {
    "demo-recorder": {
      "command": "podman",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/recordings:/app/recordings",
        "-e", "OPENAI_API_KEY=sk-your-key",
        "demo-recorder-mcp",
        "/app/run-mcp.sh", "multi-stdio"
      ]
    }
  }
}

对于Docker：

{
  "mcpServers": {
    "demo-recorder": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-v", "/path/to/recordings:/app/recordings",
        "-e", "OPENAI_API_KEY=sk-your-key",
        "demo-recorder-mcp",
        "/app/run-mcp.sh", "multi-stdio"
      ]
    }
  }
}

注：要从容器访问本地开发服务器，请参阅访问主机服务.

容器HTTP/SSE模式（备选）

对于OpenAI响应API或远程访问：

# Build HTTP image
podman build -f Dockerfile.http -t demo-recorder-mcp:http .

# Start container
podman run -d --name demo-recorder \
  -p 8081:8081 -p 8080:8080 \
  -v ./recordings:/app/recordings \
  -e OPENAI_API_KEY=sk-your-key \
  demo-recorder-mcp:http

添加到光标MCP设置：

{
  "mcpServers": {
    "demo-recorder": {
      "url": "http://localhost:8081/mcp/",
      "transport": "streamable-http"
    }
  }
}

______________________________________________________________________

主机模式独占： `maximize_window` 工具

主机模式包括 maximize_window 该工具（在容器模式下不可用）填充屏幕以获得更好的录制质量，同时保持窗口标题稳定：

browser_navigate(url="https://example.com")
maximize_window(window_title="Google Chrome")  # RECOMMENDED - fills screen, stable title
start_recording(window_title="Google Chrome")
# ... demo actions ...

建筑

┌─────────────────────────────────────────────────────────────────┐
│                        Container Mode                            │
│  ┌───────────────┐  ┌───────────────┐  ┌─────────────────────┐  │
│  │    Xvfb       │  │   Playwright  │  │   Demo Recorder     │  │
│  │  DISPLAY=:99  │◄─│    Browser    │  │   MCP (FFmpeg)      │  │
│  │  2560x1440    │  │   (Firefox)   │  │                     │  │
│  └───────────────┘  └───────────────┘  └─────────────────────┘  │
│         │                                        │               │
│         └──────────► x11grab capture ◄───────────┘               │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                          Host Mode                               │
│  ┌───────────────────────┐      ┌─────────────────────────────┐ │
│  │    Playwright MCP     │      │      Demo Recorder          │ │
│  │  (separate server)    │◄────▶│      MCP (FFmpeg)           │ │
│  │  browser automation   │      │   AVFoundation/gdigrab      │ │
│  └───────────────────────┘      └─────────────────────────────┘ │
│            │                             │                       │
│            ▼                             │                       │
│  ┌───────────────────────┐               │                       │
│  │  Chrome/Firefox/etc   │               │                       │
│  │   (real browser)      │◄──────────────┘                       │
│  └───────────────────────┘   native screen capture               │
└─────────────────────────────────────────────────────────────────┘

可用工具

录音工具

工具	说明
`start_recording`	开始视频录制（需要 `window_title` 参数）
`stop_recording`	停止录制并保存视频文件
`recording_status`	检查是否正在录制

音频工具

工具	说明
`text_to_speech`	生成画外音（使用API键的OpenAI TTS，否则为边缘TTS）

视频编辑工具

工具	说明
`adjust_video_to_audio`	通过调整播放速度将视频持续时间与音频同步
`concatenate_videos`	将多个场景视频合并到最终演示中
`media_info`	获取媒体文件的持续时间、分辨率、编解码器信息
`list_media_files`	列出所有带有URL的录制（容器模式）

协议指南

工具	说明
`planning_phase_1`	演示计划指南-致电FIRST
`setup_phase_2`	浏览器设置指南
`recording_phase_3`	录制操作指南
`editing_phase_4`	录音后组装指南

实用工具

工具	说明
`list_windows`	列出可见窗口
`window_tools`	检查窗口管理工具的可用性
`maximize_window`	最大化浏览器窗口以填充屏幕（需要 `window_title`, 仅主机模式)

集装箱模式 还包括全部22个 Playwright浏览器工具 (browser_navigate, browser_click, browser_snapshot等等）通过代理多路复用器。

主机模式 单独安装Playwright MCP效果最佳（请参阅主机模式设置).

剧作家MCP标志： 总是使用 --browser=chrome --isolated 为了与录音机实现最佳兼容性。

项目结构

demo-recorder-mcp/
├── src/recorder/
│   ├── server.py           # Entry point (~40 lines)
│   ├── core/               # Shared types and config
│   │   ├── types.py        # WindowBounds, RecordingState, etc.
│   │   └── config.py       # Environment detection, paths
│   ├── backends/           # Recording implementations
│   │   ├── base.py         # Abstract RecordingBackend interface
│   │   ├── container.py    # x11grab + Xvfb
│   │   └── host.py         # AVFoundation (macOS), gdigrab (Win)
│   ├── tools/              # MCP tool definitions
│   │   ├── recording.py    # start/stop_recording
│   │   ├── tts.py          # text_to_speech
│   │   ├── video.py        # concatenate, adjust, media_info
│   │   ├── guides.py       # Protocol phase guides
│   │   └── windows.py      # list_windows, window_tools
│   ├── transports/         # HTTP/SSE server and multiplexer
│   │   ├── http.py
│   │   └── multiplexer.py
│   └── utils/              # Shared utilities
│       ├── ffmpeg.py       # FFmpeg helpers
│       ├── window_manager.py  # Cross-platform window detection
│       └── protocol.py     # Recording workflow guides
├── scripts/                # Container startup scripts
├── tests/                  # Test suite
├── Dockerfile              # STDIO container
├── Dockerfile.http         # HTTP/SSE container
└── pyproject.toml

基于场景的工作流

演示记录为 短片（每个10-30秒）不是一个长视频。

按场景处理

SCENE N:
1. browser_snapshot()            # Verify starting position
2. start_recording(window_title="Google Chrome")  # START recording
3. browser_wait_for(time=2)      # Viewer sees initial state
4. [scroll, click, or type]      # ACTION captured on video!
5. browser_wait_for(time=2)      # Viewer sees result
6. stop_recording()              # STOP recording
7. text_to_speech("...")         # Generate audio
8. adjust_video_to_audio(...)    # Sync video to audio
9. [Repeat for next scene]

关键：录制过程中的操作

错误（静态视频）：

browser_scroll(400)           # NOT recorded
start_recording(window_title="Google Chrome")
browser_wait_for(time=5)      # Static page
stop_recording()

正确（动态视频）：

start_recording(window_title="Google Chrome")
browser_wait_for(time=2)
browser_scroll(400)           # CAPTURED!
browser_wait_for(time=2)
stop_recording()

完整示例

集装箱模式

# === SETUP ===
browser_navigate(url="https://example.com")
browser_resize(width=1920, height=1080)

# === SCENE 1: Homepage ===
browser_snapshot()
start_recording(filename="scene1_raw.mp4")
browser_wait_for(time=2)
browser_scroll(direction="down", amount=400)
browser_wait_for(time=2)
stop_recording()

text_to_speech(
    text="Welcome. As we scroll down, see the key features.",
    filename="scene1_audio.mp3"
)

adjust_video_to_audio(
    video_filename="scene1_raw.mp4",
    audio_filename="scene1_audio.mp3",
    output_filename="scene1_final.mp4"
)

# === FINAL ===
concatenate_videos(
    filenames=["scene1_final.mp4", "scene2_final.mp4"],
    output_filename="demo_final.mp4"
)

media_info(filename="demo_final.mp4")

主持人模式（带剧作家MCP）

# === SETUP ===
browser_navigate(url="https://example.com")
maximize_window(window_title="Google Chrome")  # Fills screen, keeps title stable
# No need to wait - maximize doesn't have animation like fullscreen

# === SCENE 1: Homepage ===
browser_snapshot()
start_recording(filename="scene1_raw.mp4")
browser_wait_for(time=2)
browser_evaluate(function='() => { window.scrollBy({ top: 400, behavior: "smooth" }); }')
browser_wait_for(time=2)
stop_recording()

text_to_speech(
    text="Welcome. As we scroll down, see the key features.",
    filename="scene1_audio.mp3"
)

adjust_video_to_audio(
    video_filename="scene1_raw.mp4",
    audio_filename="scene1_audio.mp3",
    output_filename="scene1_final.mp4"
)

# === FINAL ===
concatenate_videos(
    filenames=["scene1_final.mp4", "scene2_final.mp4"],
    output_filename="demo_final.mp4"
)

media_info(filename="demo_final.mp4")

配置

环境变量

变量	默认值	描述
`OPENAI_API_KEY`	（none）	TTS的OpenAI API密钥
`RECORDINGS_DIR`	`~/recordings` （主机）， `/app/recordings` （容器）	输出目录
`VIDEO_SERVER_PORT`	`8080`	视频HTTP服务器端口（容器）
`VIDEO_SERVER_HOST`	`localhost`	视频服务器主机名

文本转语音

这 text_to_speech 工具会自动选择最佳可用引擎：

发动机	使用时	声音
OpenAI TTS	何时 `OPENAI_API_KEY` set	“onyx”（专业）
Edge TTS	回退（免费）	“en-US GuyNeural”

从容器访问主机服务

在容器模式下运行时，您可能希望为本地开发服务器录制演示（例如。， localhost:3000).默认情况下， localhost 容器内部是指容器本身，而不是您的主机。

波德曼（macOS/Linux）

Podman自动提供 host.containers.internal 它解析到您的主机：

# Navigate to your local dev server
browser_navigate(url="http://host.containers.internal:3000")

不需要额外的标志 -这对波德曼来说是开箱即用的。

重要提示： 您的开发服务器必须允许来自此主机名的连接。对于Vite，添加到 vite.config.ts:

export default defineConfig({
  server: {
    host: true,
    allowedHosts: ['host.containers.internal'],
  },
})

码头工人

Docker需要 --add-host 启用主机访问的标志：

"args": [
    "run", "-i", "--rm",
    "--add-host=host.docker.internal:host-gateway",
    "-v", "/path/to/recordings:/app/recordings",
    "-e", "OPENAI_API_KEY=sk-your-key",
    "demo-recorder-mcp",
    "/app/run-mcp.sh", "multi-stdio"
]

然后使用以下方式导航：

browser_navigate(url="http://host.docker.internal:3000")

重要提示： 您的开发服务器必须允许来自此主机名的连接。对于Vite，添加到 vite.config.ts:

export default defineConfig({
  server: {
    host: true,
    allowedHosts: ['host.docker.internal'],
  },
})

汇总表

运行时	主机名	需要额外标记
Podman 的 `host.containers.internal`	没有
Docker	`host.docker.internal`	`--add-host=host.docker.internal:host-gateway`

故障排除

主机模式：视口大于屏幕

症状： 浏览器视口延伸到屏幕边界之外，无法录制。

原因： Cursor内置的浏览器自动化与Playwright MCP冲突。

解决方案：

禁用光标浏览器自动化（设置→ 工具和MCP→ 浏览器自动化→ OFF)
使用Playwright MCP --browser=chrome --isolated 旗帜
重新启动游标

主机模式：录制期间找不到窗口

症状： start_recording 失败，出现“找不到窗口”错误。

原因： 窗口标题已更改（例如，在页面之间导航），或者检测到的是Cursor的嵌入式浏览器而不是Chrome。

解决：

使用所示的确切窗口标题 list_windows()
确保已禁用光标浏览器自动化
检查Chrome（不是Cursor）是否为活动浏览器窗口
使用 maximize_window(window_title="Google Chrome") 录制前

主机模式：多显示器/Reta显示屏问题

症状： 录制捕获了错误的屏幕或存在分辨率问题。

解决：

录制前将Chrome移动到主显示器
使用 maximize_window() 确保一致的窗口边界
对于Retina显示器，记录器会自动处理缩放

主机模式：屏幕录制权限（macOS）

症状： 录制失败或产生黑色视频。

解决方案：

系统设置→ 隐私和安全→ 屏幕录制
添加光标到允许列表
重新启动游标 （需要获得许可才能生效）

容器：找不到Windows

list_windows() 需要浏览器窗口存在：

browser_navigate(url="https://example.com")  # First!
list_windows()  # Now returns Firefox window

视频不同步

将演示分解为更短的场景（10-30秒）。长录音需要极端的速度调整。

容器HTTP：健康检查

curl http://localhost:8081/health
# {"status":"healthy","service":"demo-recorder-mcp","tools_count":36}

孤立FFmpeg进程

症状： 新录制失败或生成0字节文件。

原因： 之前的录制未正确停止，导致FFmpeg仍在运行。

解决方案：

# Check for orphaned processes
ps aux | grep ffmpeg

# Kill if found
pkill -9 ffmpeg

记录器现在可以在启动时自动清理孤立进程。

______________________________________________________________________

要避免的常见错误

❌ 不要✅ 请改为
使用Playwright MCP的光标浏览器自动化	禁用光标浏览器自动化
使用 `@anthropic-ai/mcp-server-playwright`	使用 `@playwright/mcp@latest --browser=chrome --isolated`
省略 `--isolated` flag	始终包含 `--isolated` 避免浏览器冲突
录制5分钟以上的长场景	分成10-30秒的场景，然后连接起来
跳过 `maximize_window()`	始终最大化以获得一致的窗口边界
使用Cursor的嵌入式浏览器	通过Playwright MCP使用独立Chrome

发展

# Setup
git clone https://github.com/Schimuneck/demo-recorder-mcp.git
cd demo-recorder-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Build container
podman build -t demo-recorder-mcp .
podman build -f Dockerfile.http -t demo-recorder-mcp:http .

贡献

欢迎投稿！看贡献.md.

许可证

MIT许可证-请参阅许可证.

getademo (Schimuneck)

快速接入

详细介绍

演示记录器MCP

示例：你能创造什么

特性

两种访问模式

快速入门：主机模式（推荐）

先决条件

步骤1：安装演示记录器

步骤2：配置光标MCP

步骤3：禁用光标浏览器自动化（严重！）

步骤4:macOS屏幕录制权限

步骤5：验证设置

快速入门：容器模式

构建容器

配置光标MCP

容器HTTP/SSE模式（备选）

主机模式独占： maximize_window 工具

建筑

可用工具

录音工具

音频工具

视频编辑工具

协议指南

实用工具

项目结构

基于场景的工作流

按场景处理

关键：录制过程中的操作

完整示例

集装箱模式

主持人模式（带剧作家MCP）

配置

环境变量

文本转语音

从容器访问主机服务

波德曼（macOS/Linux）

码头工人

汇总表

故障排除

主机模式：视口大于屏幕

主机模式：录制期间找不到窗口

主机模式：多显示器/Reta显示屏问题

主机模式：屏幕录制权限（macOS）

容器：找不到Windows

视频不同步

容器HTTP：健康检查

孤立FFmpeg进程

要避免的常见错误

发展

贡献

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

主机模式独占： `maximize_window` 工具