Screencast MCP

快速开始

你需要： Windows 10 或 11、Node.js 22+，以及位于 PATH 中的 ffmpeg（winget install Gyan.FFmpeg）。屏幕捕获仅支持 Windows；观看、编辑和制作工具可在任何能够运行 ffmpeg 的系统上使用。

将其添加到客户端：

客户端	方法
Claude Code	claude mcp add screencast -- cmd /c npx -y @tmhs/screencast-mcp
Claude Desktop	从最新版本下载 .mcpb 并打开（一键完成）
Cursor、VS Code 等	使用下方的 JSON 配置，或参阅连接客户端中的分步说明

{
  "mcpServers": {
    "screencast": { "command": "npx", "args": ["-y", "@tmhs/screencast-mcp"] }
  }
}

然后向 Agent 提问：

录制我的 VS Code 窗口 5 秒，期间我会重现这个错误，然后给我看看发生变化时的画面帧。

工作流中还有更多示例：用于 PR 的错误复现 GIF、README 演示、UI 验证循环、社交媒体短片、快速检查长录制内容、放大点击位置，以及一次调用完成全部编辑。

概述

Screencast MCP 为 Agent 提供了一个可操控、可推理的屏幕录制器。它通过 stdio 使用 Model Context Protocol，并将 ffmpeg 封装为一组精简、类型明确的工具，而不是一堆杂乱的标志参数。其核心能力是 观看循环：Agent 录制影像，将其采样为 PNG 帧，再查看这些帧以确认屏幕上实际发生了什么。

这些设计选择都是有意为之：

• 采集始终需要明确触发。 只有调用工具才会录制或截图——不会自动启动，也没有后台或定时采集。
• 影像可以查看。 sample_frames 会将视频转换为直接返回给模型的图像，因此“观看发生了什么”是一项一等操作，而非事后补充。
• 优先使用预设，而非原始标志参数。 画质分为 draft / standard / high；Agent 无须考虑编解码器、CRF 或像素格式。
• 默认安全。 输出会保存到 SCREENCAST_HOME 下，绝不会保存到项目检出目录中；公开仓库的 .gitignore 会阻止提交采集的媒体文件。
• 录制终会结束。 客户端断开连接时（或服务收到 SIGINT/SIGTERM 时），所有正在进行的录制都会完成最终处理，随后服务退出。每次录制也都有 maxDurationSec 时长上限（默认一小时）。因严重崩溃而中断的录制会在下次启动时进行修复处理（清理孤立录制）。

除录制和查看之外，它还可以：

• 缩放至点击位置。 使用 events: true 录制时，zoom 会滑动放大每次点击，并以圆圈标出，效果类似 Screen Studio。
• 分享前先审阅。 在支持 MCP Apps 的客户端中，stop_recording 会打开内嵌播放器，供用户剪辑视频并绘制遮挡框。
• 查找并遮盖机密信息。 find_text 使用 Windows OCR 读取屏幕，并返回可供 redact_region 使用的矩形区域。
• 一次调用，完成一次编码。 pipeline 通过单次 ffmpeg 处理完成裁剪、截取画面、遮盖、添加标注和导出。
• 录制被遮挡的窗口。 backend: "wgc" 可通过 Windows Graphics Capture 录制窗口自身的表面。

工具

共 41 个工具，分为六组。mcp-tools.json 中的清单是规范依据；测试会确保它、本文档和文档站点与 src/tools/ 保持同步。

采集

工具	用途
start_recording	启动后台录制。target = full | monitor:<index> | window:<title> | region:<x>,<y>,<w>,<h>；可选参数包括 fps、quality、audio（将 audio.source 设为 system 也可采集回环音频）、maxDurationSec（自动停止上限，默认 3600；0 = 无上限）以及 events（将点击、滚动、光标和按键记录到 <recording>.events.jsonl；keys 默认为 masked，也可设为 shortcuts）。返回会话 ID 和输出路径。
stop_recording	按 ID 停止会话。向 ffmpeg 发送正常退出信号，确保文件完成最终处理，而非被截断。返回最终路径和时长。
list_sessions	列出正在进行和已完成的会话。
get_session	查看单个会话的详细信息。
review_recording	支持 MCP Apps 的客户端中的审阅播放器：内嵌播放器，用户可拖动进度条浏览录制内容、拖动剪辑手柄并绘制遮挡框，然后导出经过剪辑和遮挡的副本（调用一次 pipeline）。stop_recording 的结果也会打开该播放器。在其他客户端中，它会返回视频详情。
player_frames	为审阅播放器预览 JPEG 帧；由播放器调用（仅应用），而非由 Agent 调用。
read_events	按视频时间读取录制的输入事件日志（点击、滚动、光标、按键）。使用 start_recording 的 events: true 参数启用。
screenshot	对 target 截取单张 PNG，并以内嵌图像形式返回，供模型查看。
list_audio_devices	列出 ffmpeg 可识别的 DirectShow 音频设备，并标出可能用于 start_recording 的系统音频回环设备。

观察

工具	用途
sample_frames	从视频中提取帧：按固定的 fps、指定的 timestamps，或仅在屏幕发生变化时提取（mode: "scenes"），以便 Agent 查看发生了什么。返回帧路径，并以内嵌图片的形式显示前几帧。
contact_sheet	将带时间戳的帧拼成一张图片（按均匀间隔，或在场景变化处取帧），让 Agent 一眼查看整个录制内容；图片以内嵌形式返回。设置 poster: true 则改为写入一张代表性帧。
screen_diff	比较两张屏幕截图／帧：提供 SSIM 分数、变化占比和变化内容的边界框，并在内嵌图片中标出变化。验证 UI 是否发生变化，以及变化是否仅出现在预期位置。
wait_for_change	监视目标，并在目标发生变化（打开对话框）或稳定下来（构建或页面完成）时返回，而不是猜测等待时间。报告耗时、变化区域，以及以内嵌形式显示的最终状态。
find_text	使用 Windows 内置的 OCR 引擎读取屏幕或帧中的文本（无需安装）：返回每一行文本及匹配项的边界框。可按标签定位按钮、检查屏幕上显示的内容，或查找密钥（`regex: "sk-
get_media_info	ffprobe 封装工具：返回时长、分辨率、fps、编解码器、容器格式和大小。

最小化编辑

工具	用途
trim	按 start 和（end 或 duration）剪切子片段。使用流复制以提高速度。
concat	将两个或更多视频拼接为一个。
convert	在 mp4、gif 和 webm 之间转换。
export_gif	导出符合大小限制的动画 GIF 或 WebP（默认：GitHub 的 10 MB 图片限制），用于 PR、issue 和 README。GIF 使用两阶段调色板；逐步降低 fps、宽度和调色板／质量，直到符合限制，并报告所用设置。

编辑画面

这些工具会重新编码（滤镜会重写像素，因此不适用流复制）。它们使用与录制相同的 draft/standard/high 预设。

工具	用途
crop	裁剪到像素矩形区域（x、y、width、height）。超出画面的矩形会被拒绝，不会静默裁切到画面范围内。
scale	调整为指定的 width 和／或 height。只设置一边时会保持宽高比；两边都设置则使用精确尺寸。
speed	通过 factor 更改播放速度（>1 加快，<1 减慢）。如果有音频，也会调整其速度。
overlay	在底层视频的指定位置叠加徽标、水印或画中画，可选择缩放并设置显示时长。
callout	定时标注：可在任意角度添加方框、文本标签和箭头，并为每项设置起止时间。标出错误、指向按钮或为步骤添加说明。
compress	通过 light/medium/heavy CRF 等级重新编码以减小文件体积；可选的 maxWidth 仅会缩小画面。
extract_audio	将音轨写入单独的文件（mp3、aac、wav 或 copy）。
normalize_audio	将响度调整到目标值（两遍 EBU R128 loudnorm）：youtube 为 −14 LUFS，podcast 为 −16，broadcast 为 −23，也可指定任意 LUFS 值。视频会直接复制；并会报告调整前后的响度。
denoise	使用 afftdn 降低稳定的背景噪声（风扇声、嗡嗡声、嘶嘶声），并根据文件测得的噪声底进行调校。视频会直接复制。
transcribe	在本地将语音转为 SRT 文件，使用 FFmpeg 8 的 whisper 滤镜（需要 whisper.cpp 模型：传入 model 或设置 SCREENCAST_WHISPER_MODEL）。字幕条目会重新编号并消除重叠。
burn_subtitles	使用捆绑字体将 SRT/ASS 字幕烧录到视频中：clean（带描边的单行字幕）或 social（深色底框上的大号粗体文本，适合静音自动播放）。
clip	精确到帧地提取一个或多个片段，并分别保存为文件。与 trim 不同，它会重新编码，因此剪切点会精确落在指定时间。
cut_idle	移除静默片段：剪掉画面静止且（有音频时）无声的部分，并在每个边缘保留一小段缓冲。会先通过 dryRun 报告结果；除非设置 useAudio: false，否则会保留静止画面上的语音。

遮挡

工具	用途
redact_region	遮挡视频中指定的矩形区域。style 可设为 box（默认，使用不可逆的纯色填充）、blur（模糊）或 pixelate（像素化）；每个区域可限制在 start/end 时间范围内，并通过 pad 扩大。

重要

redact_region 只会遮挡你指定的区域。它不会自动检测机密信息，因此无法找到你未标出的机密。默认的 box 样式使用纯色填充，且不可逆；blur 和 pixelate 的遮挡效果较弱，部分内容可能被还原，因此处理真正的机密时应优先使用 box。超出画面的区域会被拒绝，不会静默地什么也不做。

制作

制作层将原始片段处理成最终作品。合并片段的工具会先自动将每个输入规范化为统一的分辨率、帧率和音频采样率，确保不同来源的素材能够流畅合成。

工具	用途
xfade_transition	使用 xfade 转场（fade、wipeleft、slideup 等）将两个视频交叉淡化为一个。若两个片段都有音轨，音频也会交叉淡化。
assemble_highlights	将两个或多个片段拼接为一个，可使用硬切（transition: "cut"），或在每个片段之间使用 xfade 转场。
title_card	生成独立的标题卡（在纯色背景上居中显示文字，并带有静音轨道，便于合成）。文字使用内置字体，因此无需系统字体。
music_bed	在视频下方铺设音乐轨道：循环或裁剪至视频长度，淡入淡出，调整音量，并与现有音频混合（可选择闪避）。
reframe	将画面调整为 16:9、9:16、1:1 或 4:5，可使用 pad（添加黑边，不丢失内容）或 crop（填满画面，裁去溢出部分）。
zoom	平滑缩放与平移（Screen Studio 风格），聚焦到动作发生的位置，再拉远。可提供关键帧（按时间指定矩形），也可根据输入事件日志中的点击自动规划（start_recording 设置 events: true；highlightClicks 会为每次点击添加圆环），或根据屏幕变化自动规划；dryRun 会返回规划结果供调整。
export_preset	编码为适用于平台的文件（youtube、instagram_reel、tiktok、x、square、steam_trailer、vertical_reel）：调整画面比例、限制帧率，并按平台码率编码为 H.264，同时启用 faststart。steam_trailer 为添加黑边的 1080p H.264 High，采用 5.5 Mbps CBR（高于 Steam 的 5 Mbps 下限），音频为 48 kHz、-14 LUFS；vertical_reel 会将素材置于自身的模糊副本上方居中显示，音频为 -14 LUFS。
pipeline	在一个 ffmpeg 进程中完成多项编辑：可按 steps 执行 trim、crop、scale、speed、redact、callout、reframe、zoom（关键帧），并可选择以 export_preset 或 export_gif 结束，每一步均可使用对应工具的选项。只需重新编码一次，无需中间文件；还可保存配方并在下一次录制时重新运行；dryRun 会返回计划执行的命令。

目标

每个采集工具都只接受一个 target 字符串，因此 Agent 无需处理复杂的引号转义：

目标	采集内容
full	整个虚拟桌面
monitor:<index>	一个显示器；0 始终代表主显示器
window:<title>	窗口占据的屏幕矩形（标题区分大小写并优先精确匹配，否则进行子串匹配；最上层窗口优先）
window:exe=<app.exe>	该应用最上层的窗口，不依赖窗口标题
window:hwnd=<handle>	由句柄指定的一个窗口（十六进制 0x1A2B 或十进制）
region:<x>,<y>,<w>,<h>	绝对像素矩形区域

对于 window: 目标，screenshot 和 start_recording 都会报告 matchedWindow、matchCount、matchKind（exact、substring、exe 或 hwnd）以及采集到的 region。如果标题仅通过子串匹配，或有多个窗口匹配，结果会附带 windowWarning，列出候选标题，因此像 window:Code 这样的通用标题不会悄然录制错误的窗口。传入 exactTitle: true 可完全禁用子串匹配回退。

输出会写入 SCREENCAST_HOME（默认值为 <homedir>/.screencast-mcp）下的 recordings/、frames/、screenshots/ 和 edits/。任何工具也都接受显式输出路径。

编辑和制作工具会先在输出文件旁写入 <name>.partial.<ext> 文件，只有 ffmpeg 成功后才会将其重命名为最终文件，因此任务失败、超时或取消时，output 处不会留下被截断的文件。任务超时时长会根据媒体长度调整（至少 10 分钟，或媒体时长的 4 倍）；设置 SCREENCAST_JOB_TIMEOUT_MS 可覆盖该值。发送进度令牌的客户端会在任务运行期间收到 notifications/progress 更新；取消请求会停止 ffmpeg。

配置

ffmpeg 和 ffprobe 必须位于 PATH 中，或通过 FFMPEG_PATH / FFPROBE_PATH 指定；服务会在每次调用时检查，如果缺少其中任一程序，就会返回安装提示（macOS：brew install ffmpeg；Linux：apt install ffmpeg，适用于非捕获工具）。

变量	默认值	用途
SCREENCAST_HOME	<homedir>/.screencast-mcp	录制、帧、截图和编辑文件的写入位置
SCREENCAST_MAX_RECORDING_SEC	3600	默认录制时长上限（0 表示禁用）
SCREENCAST_JOB_TIMEOUT_MS	随时长变化	覆盖编辑任务超时时间
SCREENCAST_WHISPER_MODEL	无	用于 transcribe 的 whisper.cpp 模型
FFMPEG_PATH / FFPROBE_PATH	查找 PATH	显式指定 ffmpeg / ffprobe 二进制文件

用法

**工作流：**文档站点提供了包含工具调用和实际输出的复制粘贴示例：PR 缺陷复现片段、README 演示 GIF、Agent UI 验证循环、社交媒体片段、审查长录制视频、放大每次点击，以及一次调用完成整个编辑。

典型的监看循环——录制、采样、查看：

// 1. record a region for a few seconds
start_recording { "target": "region:0,0,1280,720", "quality": "draft" }
//    -> { "sessionId": "rec-…", "outputPath": "…/recordings/rec-….mp4" }

// 2. finalize the file
stop_recording { "sessionId": "rec-…" }
//    -> { "durationSec": 4.2, "finalizedGracefully": true }

// 3. look at it: the frames come back inline, so the model sees them directly
sample_frames { "input": "…/recordings/rec-….mp4", "timestamps": [0.5, 2, 3.5] }
//    -> { "frames": ["…/frames/…/frame_000_0.5s.png", …], "inlineImages": 3 }
//       + 3 image blocks the client shows to the model

不知道该看哪里？sample_frames { "input": "…", "mode": "scenes" } 只会返回屏幕实际发生变化的帧（以及开场帧），并附带其 frameTimes。屏幕录制内容大多是静态的，因此这种方式通常比固定频率采样便宜得多。sceneThreshold（默认值为 0.1）用于设置多大的变化才算变化；在 fps 模式下，dedupe: true 会丢弃近乎相同的帧。

screenshot { "target": "window:My App" } 可一次性截取静态画面，并会以内嵌形式返回图像。

内嵌图像为缩小后的 JPEG（maxImageWidth 默认值为 1280），且每次调用数量有限（maxInlineImages 默认值为 8，上限为 20）；全分辨率 PNG 会保留在磁盘上。传入 returnImage: false / returnImages: false 可仅获取路径。

每次调用中，sample_frames 最多写入 maxFrames 帧（默认值为 100，上限为 1000）。在 fps 模式下，它会先探测视频；如果采样率会超过上限，就会降低采样率，以确保帧仍覆盖整个视频，并通过结果中的 capNote 说明处理方式。

提示词和资源

除工具外，服务还提供提示词：客户端（例如 Claude Code 和 VS Code）会将这些现成工作流显示为斜杠命令。

提示词	功能
bug-repro-clip	录制、找到缺陷发生时刻、检查是否包含机密信息、剪辑、添加注释，并为问题导出 GIF。
demo-gif	录制功能演示，并导出适合放入 README 或 PR 的小型 GIF。
verify-ui-change	先截图，再进行更改，等待屏幕稳定，然后对比并确认文本。
review-recording	总结录制视频中的内容，并附上时间戳。

服务还提供资源，客户端无需使用文件系统工具即可列出并附加录制内容：screencast://sessions（所有会话）、screencast://sessions/{id}（单个会话）和 screencast://sessions/{id}/poster（JPEG 预览帧）。录制开始或停止时，客户端会收到通知。

Windows 说明

• 多显示器偏移。 gdigrab 没有“捕获第 N 个显示器”的选择器，因此指定显示器时会捕获整个虚拟桌面，并裁剪到该显示器的像素边界（来自 System.Windows.Forms.Screen.AllScreens）。monitor:1 会捕获位于实际偏移位置的第二个显示器；monitor:0 始终是主显示器。
• 窗口捕获会解析窗口在屏幕上占据的矩形区域并捕获该区域，而不是窗口自身的表面——对于由 GPU 或 DirectComposition 合成的窗口（Chrome、Electron、UWP），gdigrab 原生的 title= 捕获会返回空白帧。可按标题指定目标，或使用 window:exe=Code.exe（该应用最上层的窗口）或 window:hwnd=0x1A2B（一个指定窗口），而不依赖标题；结果会报告匹配的标题。窗口必须可见、位于最上层且未最小化（最小化的窗口会被拒绝，并显示明确错误）；捕获内容包括绘制在该矩形区域上的所有内容。对于 start_recording，矩形区域在开始时固定不变。也可使用 backend: "wgc"（见下文）来捕获窗口自身。
• Windows Graphics Capture（backend: "wgc"，FFmpeg 8+）。通过句柄捕获窗口的自身表面，即使其他窗口遮挡它也可以。该方式用于 screenshot 和 find_text 时需要 1–2 秒，而非约 0.2 秒，因此默认不启用。用于 start_recording 时，即使窗口被遮挡、移动或处于后台，也会录制其客户区。gfxcapture 仅在窗口呈现内容时才输出帧，因此一个小型录制器进程每 200 ms 重绘窗口的一个像素，并按请求的 fps 重复输出最新帧；与 ffmpeg 一样，按 q 后停止，因此 stop_recording 和 maxDurationSec 的工作方式相同。首帧需要一两秒；捕获完成后，start_recording 才会返回。目前 wgc 不支持音频。
• 独占全屏应用在 gdigrab 下通常会产生黑帧；请以无边框窗口模式运行源应用，以确保可靠捕获。
• 系统音频需要环回设备。gdigrab 仅支持视频，因此当 audio.source = system 时，start_recording 会从单独的 dshow 输入捕获音频。Windows 没有原生环回功能，因此需要虚拟音频设备（启用 Stereo Mix，或安装 screen-capture-recorder 的 virtual-audio-capturer 或 VB-CABLE 等驱动）。运行 list_audio_devices 查找设备。不支持麦克风捕获，这是有意为之。

威胁模型

警告

屏幕捕获可能会记录捕获瞬间屏幕上的任何内容——密码、令牌、私信和其他机密。window: 捕获的是窗口占据的屏幕矩形区域，因此覆盖层、通知或绘制在其上方的其他窗口也会被捕获。默认情况下，请将录制内容、屏幕截图和采样帧视为敏感信息。

• 捕获始终需要明确操作。 不会自动触发；必须通过明确调用工具才能进行捕获。
• 输出保留在本地。 文件只会写入本地文件系统，不会上传、流式传输或发送到任何地方。
• 仓库公开，捕获内容私密。 .gitignore 会屏蔽录制内容、帧、屏幕截图以及常见的视频和图像输出，避免测试媒体意外提交。
• 分享前先检查。 将文件交给其他工具或人员之前，请先查看采样帧或检查录制内容，以了解其中包含什么。在支持 MCP Apps 的客户端中，stop_recording 和 review_recording 会打开内嵌播放器，供用户浏览整个录制内容，并在内容离开本机前绘制遮挡框。播放器通过 MCP 连接获取帧；不会启动本地 Web 服务。
• 遮挡范围仅限于你指定的内容。 redact_region 只会遮挡你指定的矩形区域。find_text 可以帮助定位这些区域：使用 regex: "sk-|ghp_|api.?key" 之类的查询执行 OCR，并设置 redact: true，即可返回可直接使用的矩形区域。但 OCR 只能尽力识别，可能会漏掉较小或风格化的文字，因此只能将其作为辅助，而非保证。使用默认的 box 样式进行实心、不可逆的填充，并在分享前检查输出。
• 输入事件日志绝不会记录你输入的内容。 start_recording 的 events: true 仅会在该次录制期间通过辅助进程捕获鼠标和键盘输入；辅助进程会随录制结束而退出（或随服务退出）。默认情况下，按键会被masked：日志只会记录按键按下，不会记录具体按键。keys: "shortcuts" 也会记录与 Ctrl、Alt 或 Win 同时按下的组合键（如 Ctrl+S）；普通输入、Shift 加字母以及 AltGr 字符仍会被遮蔽，而且任何模式都不会记录文本。光标位置和点击仍会暴露你指向的位置，因此请将 .events.jsonl 和旁边的录制文件一样谨慎处理。
• 系统音频同样敏感。 当 audio.source = system 时，录制内容会捕获机器上播放的所有声音（通话音频、通知、媒体）。请以与视频相同的谨慎程度处理包含音频的录制内容。

项目结构

.
├── src/
│   ├── index.ts          # MCP server entry (stdio); registers every tool, reaps orphans
│   ├── prompts.ts        # MCP prompts (workflows as slash commands)
│   ├── resources.ts      # MCP resources (sessions, posters)
│   ├── wgcRecorder.ts    # recorder process for backend: "wgc"
│   ├── tools/            # one file per tool
│   ├── utils/            # pure builders and helpers (ffmpeg args, targets, sessions, ...)
│   └── __tests__/        # vitest: unit, ffmpeg integration, guarded local-capture harness
├── assets/               # bundled fonts and the review player (assets/ui)
├── docs/                 # GitHub Pages site (scripts/build-docs-pages.mjs writes the recipe pages)
├── scripts/              # Claude Desktop bundle (.mcpb) and docs page builders
├── mcp-tools.json        # canonical tool manifest (kept in sync with src/tools)
├── server.json           # MCP Registry listing (name matches package.json mcpName)
├── .github/workflows/    # CI, release, npm publish, Pages, ecosystem drift check
├── ROADMAP.md · CONTRIBUTING.md · SECURITY.md · LICENSE
└── package.json

开发

git clone https://github.com/TMHSDigital/screencast-mcp.git
cd screencast-mcp
npm install
npm run build      # tsc -> dist/
npm test           # vitest: unit tests, plus the ffmpeg integration suite when ffmpeg is on PATH
npm run dev        # tsx watch

若要从客户端运行构建，请将其指向 dist/index.js："command": "node"、"args": ["C:/path/to/screencast-mcp/dist/index.js"]。

集成测试套件（src/__tests__/integration）会通过 ffmpeg，使用 lavfi 生成的测试素材运行实际的 edit 和 produce 构建器，并检查探测结果（时长、尺寸、流、响度）。如果缺少 ffmpeg，则会跳过；设置 REQUIRE_FFMPEG=1 后，缺少 ffmpeg 将导致失败，CI 的 Linux 任务就是这样配置的。

CI 的无头 Linux 运行器无法测试捕获流程，因此端到端测试脚本设有一个标志，默认跳过：

RUN_LOCAL_CAPTURE_TESTS=1 npm test   # Windows + ffmpeg + a real display

贡献

欢迎提交问题和拉取请求——请参阅 CONTRIBUTING.md 和行为准则。安全问题请通过 SECURITY.md 报告。

许可证

本项目基于 CC-BY-NC-ND-4.0 许可证发布：可免费用于非商业用途并分享，但须注明出处且不得修改。如需用于其他用途，请提交问题。