Clipy

@clipy/mcp

让你的 AI Agent 访问你在 Clipy 中的屏幕录制内容。

在 Clipy monorepo 中开发。可在 github.com/manovagyanik1/clipy-mcp 浏览源码并提交问题的公开镜像为 (MIT)，并与每次 npm 发布保持同步。

这是一个 Model Context Protocol (MCP) 服务。它让 Claude、Cursor、Windsurf 和其他支持 MCP 的 Agent 搜索你的录制内容，并读取其中的转录文本和 AI 摘要——因此你可以在不离开 Agent 的情况下执行诸如 “把这段 Bug 报告录制内容转成 Linear 工单” 之类的操作；此外，通过 record 工具，还可以 以无头模式录制 Web 应用，并将其作为 Clipy 录制内容取回（“构建这个功能，然后录下结果”）。

跨界面的权威操作约定见 clipy.online/agents.md。如需准确的已连接 MCP 版本和架构，请使用标准的 tools/list 请求。

读取工具需要 recordings:read 范围，所有密钥默认都包含此范围。写入工具——record、会话工具（start_recording、add_marker、add_chapter、 stop_recording、abort_recording）以及 replace_transcript——还需要密钥包含 ingest 范围（“录制并上传”），服务会强制执行此要求。get_edit_transcript 和 edit_recording 需要 recordings:write 范围。只有 recordings:read 权限的密钥可以读取你的录制内容，但不能创建、修改或删除任何内容。

设置

使用 Clipy CLI 登录一次：

npx @clipy/cli@latest login

系统会打开浏览器；点击一次 Approve。密钥会保存到 ~/.config/clipy/config.json，而此服务会读取该文件——因此无需将密钥复制到任何地方，也不会有机密信息进入 shell 历史记录或 MCP 配置。

然后将此服务添加到你的 MCP 客户端。

Claude Code

--scope user 标志会为所有项目全局安装 Clipy。不加此标志时， claude mcp add 默认使用 local 范围（仅限当前文件夹）：

claude mcp add --scope user clipy -- npx -y @clipy/mcp

Codex

这会将服务写入全局 ~/.codex/config.toml，因此它在每个 Codex 会话中都可用：

codex mcp add clipy -- npx -y @clipy/mcp

或者手动将其添加到 ~/.codex/config.toml：

[mcp_servers.clipy]
command = "npx"
args = ["-y", "@clipy/mcp"]

Claude Desktop / Cursor / Windsurf

直接编辑对应的用户级配置（claude_desktop_config.json、~/.cursor/mcp.json， 或 Windsurf MCP 配置）：

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

仅当你未在此计算机上使用 clipy login 时，才添加 "env": { "CLIPY_API_KEY": "clipy_sk_live_xxx" } 配置块。

显式设置密钥

如果没有可读取的 clipy login，例如在 CI 或容器中，或者你有意使用不同于已登录密钥的密钥，请使用 CLIPY_API_KEY。显式设置的环境变量始终优先于配置文件。前往 https://clipy.online/settings/api-keys 创建密钥（仅显示一次）。

切勿将密钥直接写入服务的启动命令，例如 "command": "sh", "args": ["-c", "CLIPY_API_KEY=… npx -y @clipy/mcp"]。命令行 参数可通过进程表（ps、/proc）被所有本地进程看到，因此放在那里的密钥实际上对计算机上的所有人可见。请改为将密钥放入 env 块中。（claude mcp add --env … / codex mcp add --env … 会替你写入该 env 块——密钥只会出现在这条设置命令的 argv 中，不会出现在长时间运行的服务进程中。）

托管连接器

你也可以无需安装任何内容即可连接。Clipy 在 https://clipy.online/api/mcp 上运行此服务（Streamable HTTP）。

• Claude 和 ChatGPT 等连接器界面使用 OAuth 登录。发现流程从 https://clipy.online/.well-known/oauth-protected-resource 开始。
• 其他客户端发送 Authorization: Bearer <Clipy API key>。
• 只有 recordings:read 范围的密钥只能使用读取工具。

面向 MCP 目录和审核者

Clipy 保留了一个演示账户，其中有三个示例录屏：Bug 演示、UI 反馈和产品演示。目录可通过发送邮件至 [email protected] 获取只读测试密钥。

工具

工具	功能
search_memory	一次搜索整个 Clipy 记忆库 — 搜索用户录制的每段屏幕录像 以及 导入的每段视频 — 并返回匹配片段的时间戳和可跳转到相应位置的 URL。匹配方式既包括语义匹配，也包括字面匹配，因此搜索“登录流程”也能找到有人提到“身份验证界面”的片段。用户提到他们展示、录制或观看过的内容时，请优先使用此工具；下面的单个库工具各自只能查看一半内容。每条结果都包含 kind（recording 或 context），用于指示接下来应读取哪个工具；resolution 用于说明时间戳表示精确时刻还是约 50 秒的时间段；semantic.status 用于判断是否可以将空结果视为“没有录制内容”。
search_recordings	按关键词（标题 + 描述）搜索录制内容。
list_recordings	列出最近的录制内容。
get_recording	获取单条录制内容的元数据（状态、时长、转录文本／摘要状态）。
get_transcript	获取完整的带时间戳转录文本 + 纯文本。
get_summary	获取 AI 摘要：简要概述、要点、行动项。
get_edit_transcript	获取录制内容的可编辑转录文本（需要 recordings:write 权限范围，因为其中包含被剪掉词语的文本）：每个词及其索引、原始时间线上的开始／结束时间（毫秒）、filler 标记（um、uh、er、hmm），以及当前版本已剪掉词语的 removed 标记；还包含传给 edit_recording 的 revision。通过 fromWord／limit 分页。
edit_recording	根据转录文本编辑视频（需要 recordings:write 权限范围）：剪掉词语范围或毫秒范围、移除所有填充词、恢复剪辑，或启用点击自动缩放（autoZoom，适用于 Mac 和 Windows 录制内容）。Clipy 会保留原始内容，因此在所有者删除原始内容前，都可以恢复剪辑；分享链接保持不变，并会在渲染完成后切换到新版本。支持 dryRun 和 expectedRevision。
get_browser_diagnostics	获取经隐私处理的已访问路由、控制台警告／错误、页面异常和失败的 fetch/XHR 元数据。证据会明确标记为由页面报告；绝不会采集标头、正文、Cookie、令牌、输入值或原始查询值。
get_interactions	分页获取有限数量的已整理路由、指针采样、语义点击、派生拖动、滚动片段、指针停留、粗略输入记录（绝不包含输入值或精确按键次数）和高亮标记。可通过 fromMs／toMs／types 筛选，设置 limit（1–250，默认 100），并在筛选条件不变时继续使用 pagination.nextCursor。报告数据源覆盖范围和准备状态；停留不代表用户一定在关注，坐标对应采集视口，而非变换后的播放帧。
wait_for_artifacts	轮询，直到录制内容的转录文本／摘要处理完成。
download_recording	将 MP4 下载到本地，以便自行剪辑或提取帧（例如使用 ffmpeg）。
get_key_moments	获取关键时刻：时间戳、字幕和点击坐标。
get_agent_context	获取完整的 Agent 上下文包（摘要 + 交互时间线 + 关键时刻 + 转录文本 + 可用的浏览器诊断），格式为 Markdown。
record	以无头模式录制 Web 应用并上传为 Clipy 录制内容；返回分享链接和 Agent 上下文 URL。支持 type（录制类型）、viewports（将多种屏幕尺寸录入同一视频）、storageState／userDataDir+profileDirectory／initScript（在登录状态下录制），以及会成为静音录制内容转录文本的带时间戳 notes。需要此服务环境中安装 Playwright，并使用具有 ingest 权限范围的密钥（见下文）。
start_recording	启动录制会话，在你工作期间持续录制（使用你自己的浏览器工具操作页面、运行命令等）。支持 type、storageState／userDataDir+profileDirectory／initScript，以及 exposeCdp（获取 CDP 端点和页面内的 window.__clipyMark／window.__clipyChapter 桥接接口，以操作录制中的页面）。达到 maxSeconds（默认 600）后会自动停止并上传，因此不会无限录制。
add_marker	在活动会话中插入旁白标记（使用实时时钟，或通过 atSeconds 回填时间）——标记会成为录制内容的转录章节。可携带两种来源之一的证据：clipy-verified（assertSelector／assertText／assertUrl），由 Clipy 检查页面；或 driver-attested（observed + verdict），由你报告自己的工具观察到的内容。Clipy 验证的结果会显示判定图标（✓ 通过、✗ 失败，可通过 failMode 中止、⚠ 未验证——绝不会静默通过）；driver-attested 结果则会显示较弱的保留图标（≈），避免两者乍看时混淆，并分别统计到不同的分段中。导航和控制台错误会自动以 [auto] 标记添加。
add_chapter	在活动会话中插入 === CHAPTER: <label> === 分界线——将录制内容拆分为命名章节（非常适合前后对比演示）。
stop_recording	结束会话：关闭浏览器、上传内容，并返回分享链接和 Agent 上下文 URL。
abort_recording	丢弃活动会话；不会上传任何内容。
list_context_documents	列出用户的上下文文档——他们通过 clipy context import 导入的 YouTube 视频和本地视频文件，供 Agent 读取。这是一个独立于用户自行录制的屏幕录像的库。
get_context_document	获取单个上下文文档的元数据：来源、时长、标签、服务端分类（视频类型、是否需要视觉证据、计划中的片段），以及现有的转录文本／帧信息。不包含转录文本本身。
read_context_document	以整理后的 Markdown 形式读取上下文文档——包含标题、元数据，以及穿插帧说明的带时间戳转录文本。接受 startMs／endMs，可逐段阅读两小时的视频，而不是一次性将内容全部载入上下文。
update_recording	重命名录制内容或编辑其描述（需要 recordings:write 权限范围）。
organize_recording	将录制内容归入文件夹，并添加或移除标签（需要 recordings:write 权限范围）。
set_recording_privacy	在公开、受限和私密之间切换分享链接的隐私设置。绝不会邀请或通过电子邮件通知任何人（需要 recordings:write 权限范围）。
list_folders / create_folder	管理带 ID 的文件夹；按名称创建时具有幂等性。
list_comments	获取评论串：带时间戳的评论、回复和已解决状态。仅显示作者姓名（需要 comments:read 权限范围）。
add_comment	以密钥所有者身份在某个时刻发表评论或回复。评论串中的所有人都会收到通知（需要 comments:write 权限范围）。
get_analytics	获取观看次数、独立观看者人数、完成率和观看者名单（需要 analytics:read 权限范围）。免费账户只能获取总计数据。
upload_video	从此计算机上传 WebM、MP4 或 QuickTime .mov 视频，并获取其分享链接和 Agent 上下文链接（需要 ingest 权限范围）。
delete_recording	永久删除录制内容。confirm 必须重复填写该 ID（需要 recordings:delete 权限范围，通过 clipy login --allow-delete 获取）。
replace_transcript	使用你编写的文本替换录制内容的转录文本（需要 ingest 权限范围）。请先调用 get_transcript 并传入其 revision；若版本过期，系统会拒绝替换，而不会覆盖并发编辑。摘要会自动重新生成。内容会标记为经 Agent 编辑，绝不会冒充语音转文本结果。
读取工具接受录制内容的公开 ID（分享 URL 中的 slug）或完整的
https://clipy.online/video/<id> URL。

仅 CLI 支持捕获真实屏幕。 这些工具会录制无头 Chromium 页面。 如需录制实际屏幕或单个应用窗口（macOS 上的 Mac 应用、Linux 上的 X 显示；已登录的真实浏览器），请使用 Clipy CLI：clipy record --source screen --window "<app>"。

使用 record

record 会在无头 Chromium 中打开 URL（可在 CI / 云沙箱中运行，无需显示器），录制几秒钟并将内容流式传输到 Clipy，然后返回 ID，供你调用 wait_for_artifacts 和 get_agent_context 读取录制内容。它需要：

1. 运行此 MCP 服务的环境中安装 Playwright：

   npm install -g playwright && npx playwright install chromium
   

2. 拥有 “Record & upload”（ingest） 权限的 API 密钥——在 clipy.online/settings/api-keys 创建密钥时选择该权限。

参数：url（必填，http/https）、durationSeconds（默认值为 15，最大值为 300，按每个视口轮次应用）、name、description、type（录制类型——bug_report、 feature_request、product_demo、walkthrough_tutorial、feedback_review、 discussion_talk、other，以及别名）、viewports（例如 mobile,desktop 或 390x844,1440x900——依次录制到同一视频中，画面尺寸设为最大视口尺寸，每轮都会缓慢滚动并自动添加章节）、storageState / initScript（路径，不会记录到日志中）、notes，以及 width/height（默认值为 1280×720，设置 viewports 时会忽略）。

录制需要登录的页面。 storageState 只会按其 JSON 内容设置数据（cookies + localStorage），无法还原完整的浏览器身份（IndexedDB、service workers、部分跨域身份验证）。如需完整身份，请传入 userDataDir——Chrome 的用户数据根目录 （macOS：~/Library/Application Support/Google/Chrome）——有以下两种模式：

• 复制指定的配置文件（推荐）。 添加 profileDirectory（"Profile 1"、"Default"、…… ——即 chrome://version → Profile Path 中显示的确切文件夹）。Clipy 会将该配置文件复制到临时根目录，并使用副本进行录制，因此不会打开或修改你的实际配置文件，上传后也会删除副本。工具结果会说明复制情况（配置文件名称、字节数，以及复制时 Chrome 是否正在运行的警告）。

  ⚠️ macOS：复制后 Cookie 登录状态可能无法保留。 Chrome 使用 Chrome Safe Storage Keychain 密钥加密 Cookie；录制器附带的 Chromium 会查找 Chromium Safe Storage。因此，在 macOS 上，复制的配置文件可能会启动一个看似使用了你的身份、但在基于 Cookie 的会话中实际已静默退出登录的浏览器——基于 localStorage / Preferences 的会话仍可正常使用。这是 Playwright 与 Chrome 之间原本就存在的限制，并非复制过程引入的问题；复制情况说明中也会再次提示。如果录制开始时已退出登录，原因就在这里。 请使用 CLI 的 clipy record --source screen 录制真实浏览器，或操控你自己的浏览器，并通过 add_marker 的 observed/verdict 附加证据。

• 直接打开 Default 配置文件。 省略 profileDirectory。Clipy 会打开根目录下的 Default 配置文件并向其中写入数据，因此如果 Chrome 正在运行并锁定该配置文件，就会拒绝操作——请先退出 Chrome。如果目录看起来像真实的 Chrome 根目录，结果会附带 userDataDirWarning，说明这一点，并建议改用 profileDirectory（临时副本）或 CLI 的 --source screen。除非你明确想直接使用原配置文件，否则建议采用这些方式。

Playwright 会移除 Chromium 的 --profile-directory（无论传入哪个目录，它始终会加载其中的 Default），因此复制是录制指定配置文件的唯一方式。将 userDataDir 指向配置文件子目录（.../Chrome/Default）会被拒绝——从该目录启动会静默录制一个空白且未登录的配置文件。

storageState 与 userDataDir 不能同时使用；profileDirectory 必须与 userDataDir 一起使用。

工作前检查摄像头

record 和 start_recording 都会返回一个 source 对象，用于描述实际录制的内容。该对象会在开始录制时重新解析，包含重定向后的 url、页面 title 和录制 viewport：

"source": {
  "kind": "headless_browser",
  "title": "Orders — Admin",
  "url": "https://app.example.com/orders",
  "viewport": { "width": 1280, "height": 720 }
}

在投入大量工作之前，请将其与驱动程序正在操作的界面进行对比。之所以需要这样做，是因为由驱动程序验证的证据只能证明驱动程序观察到了什么，却无法将其与摄像头拍摄到的内容关联起来——完全可能在拍摄错误内容的画面上留下真实可信的标记。Clipy 绝不会替你聚焦或置前任何窗口或标签页；让驱动程序和摄像头指向同一个界面是调用方的职责。

这里的 kind 始终为 headless_browser：这些工具录制的是 Clipy 所拥有的无头页面。录制真实应用窗口或显示器只能通过 CLI 完成 （clipy record --source screen --window "<app>"），因此不会报告窗口 ID 或窗口标题——返回空值或虚构值，恰恰会造成此字段旨在避免的虚假信心。

标记上的证据：两种来源

add_marker 可携带的证据恰好有两种来源——分别统计和呈现，绝不合并：

来源	方式	含义
clipy-verified	assertSelector / assertText / assertUrl	Clipy 检查了录制页面本身。证据最有力。呈现为 [assert ✓ verified-by-clipy; …]、[ASSERT ✗ verified-by-clipy; …]；如果无法检查，则呈现为 [ASSERT ⚠ clipy could not evaluate — …]。
driver-attested	observed + verdict（两者都必需）	由你报告自己的工具看到了什么。Clipy 只保证你这么说了，而非已进行验证；录制的画面可以证伪该说法。呈现时使用保留态符号而非判定符号：[≈ ASSERT driver-attested; observed=…] 或 [≈ FAILED driver-attested; observed=…]。

当你的 Agent 使用自己的浏览器/工具进行操作，而 Clipy 同时进行录制时（例如 CLI 上的 --source screen），或者没有 Clipy 所有的页面可供断言时，请使用 driver-attested。它比 clipy-verified 弱，但远强于普通文字说明。转录开头的 [verification] 注释会分别列出两者，例如： [verification] 3 clipy-verified: 2 passed, 1 failed · 2 driver-attested: 2 passed, 0 failed。

通过 CDP 驱动录制页面（start_recording + exposeCdp: true）

将 exposeCdp: true 传给 start_recording 后，录制浏览器会开放一个 Chrome DevTools Protocol 端点；结果会返回 cdpHttpUrl + cdpUrl。连接你自己的 Playwright，在 Clipy 录制页面的同时进行操作：

const { chromium } = require("playwright");
const browser = await chromium.connectOverCDP(cdpHttpUrl);
const page = browser.contexts()[0].pages()[0]; // the page being recorded
await page.goto("http://localhost:3000/settings");
await browser.close();                          // detaches; the recording keeps going

默认关闭——开启期间，任何本地进程都可以连接到该浏览器。CLIPY_DISABLE_CDP=1 是强制关闭开关，可确保 CDP 关闭。注意事项：录制的页面是 contexts()[0].pages()[0]（你新建的 context 不会被捕获）；通过 CDP 连接时，page.viewportSize() 会返回 null；要更改 viewport，请使用 newCDPSession + Emulation.setDeviceMetricsOverride，而不是 setViewportSize。

页面内桥接（无需额外调用工具）。 开启 exposeCdp 后，录制页面还会暴露 window.__clipyMark(text, opts?) 和 window.__clipyChapter(label)，让你的 CDP 驱动程序可以在页面内添加已验证的标记/章节：

await page.evaluate(() =>
  window.__clipyMark("saved the form", { assertSelector: ".toast", assertText: "Saved" }),
);
await page.evaluate(() => window.__clipyChapter("AFTER — fix applied"));

opts 与 add_marker 一致（assertSelector / assertText / assertUrl / failMode）； assertText 必须搭配 assertSelector（否则调用会被拒绝），而 failMode: "abort" 下断言失败会丢弃会话——注释和统计结果与工具调用相同。

配置

环境变量	必需	默认值	说明
CLIPY_API_KEY	否	来自 ~/.config/clipy/config.json 的 apiKey	你在 /settings/api-keys 获取的个人密钥。仅当此计算机上尚未运行 clipy login 时才设置；设置后将覆盖配置文件中的值。
CLIPY_API_URL	否	https://clipy.online	用于可自托管/暂存环境的覆盖值。

隐私

你的密钥只能读取你自己的录音。你可以随时在 /settings/api-keys 撤销密钥。服务在你的机器上本地运行；除了通过 HTTPS 发送到 Clipy API，你的密钥不会发送到任何地方。