vidalytics

@vidalytics/mcp

一键设置，通过 Model Context Protocol 将你的 AI 编码助手连接到 Vidalytics 视频分析数据。

支持 Claude（CLI 和桌面应用）、Windsurf、Cursor，以及任何其他兼容 MCP 的客户端。

设置

npx @vidalytics/mcp install

就这么简单。安装程序会检测已安装的 AI 客户端，让你选择要配置的客户端，并为其完成连接。重启客户端后，首次使用时会打开浏览器窗口进行 OAuth 授权。

Cursor

或通过安装程序设置：

npx @vidalytics/mcp install --client cursor

或手动设置——将以下内容添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "vidalytics": {
      "url": "https://api.vidalytics.com/public/v1/mcp"
    }
  }
}

重启 Cursor。首次使用时，浏览器窗口会打开，以便通过你的 Vidalytics 账户进行 OAuth 授权——无需设置 API 密钥或环境变量。

功能

• 通过检查配置文件、应用目录、$PATH 中的二进制文件以及应用程序包（例如 macOS 上的 /Applications），检测已安装的 MCP 客户端（Claude CLI、Claude Desktop、Windsurf、Cursor）
• 显示交互式清单（默认选中检测到的客户端），让你只配置所需的客户端；也可以使用 --client 以非交互方式选择
• 在所选客户端的配置中添加 Vidalytics 作为 MCP 服务
• 写入后进行验证：配置有效且 MCP 服务可访问
• 对于非交互式终端（CI）以及使用任何显式选择标志（--client、--all、--yes）的情况，将跳过清单并按预期执行

可用工具

连接后，你的 AI 助手即可使用以下工具。

许多写入工具（设置、章节、字幕、标签、CTA、暂停画面、缩略图）会将更改保存到视频的草稿中——调用 publish_video 使更改生效。写入工具需要读写授权；只读连接会返回 SCOPE_INSUFFICIENT。

预览更改。 update_video_settings 接受 dryRun，可验证并返回更改前后的差异，而不保存。其他基于草稿的写入工具没有 dryRun；可先保存到草稿，再使用对应的 get_*/list_* 工具（例如 get_video_chapters、get_video_tags、get_video_captions）读回内容进行预览，然后再调用 publish_video。如果删除操作只移除了尚未发布的草稿更改，则在发布前也可以撤销；如果删除已发布的内容，则会在下次发布时生效。

视频与元数据

工具	说明
set_user_context	启用分析功能前，必须先调用此工具
list_videos	分页列出视频
get_video	获取视频详情
get_video_by_embed_guid	根据嵌入 GUID 查找视频
update_video	更新视频标题或文件夹
get_video_embed	获取嵌入代码和配置
get_video_settings	获取播放设置（自动播放、控件等）
update_video_settings	将播放设置更新为草稿（dryRun 仅进行验证并返回差异）
duplicate_video	复制视频并发布副本
publish_video	发布视频待处理的草稿设置

分析

工具	描述
get_video_stats	查看次数、播放率、观看时长、转化次数
get_video_dropoff	按百分比查看观众留存情况
get_video_percentage_watched	到达各个时间点的观众百分比
get_video_live_metrics	实时活跃观众数和观看率
get_videos_stats_batch	一次获取最多 30 个视频的统计数据
get_videos_timeline	获取最多 5 个视频的时间线统计数据

章节、字幕和标签

工具	描述
get_video_chapters	列出视频章节及其启用状态
set_video_chapters	替换视频的章节标记（草稿）
get_video_captions	列出视频的字幕轨道
add_video_caption	根据提供的文本添加或替换字幕轨道（草稿）
delete_video_caption	移除某种语言的字幕
get_video_tags	列出视频的标签和自定义变量
set_video_tags	设置视频的完整标签列表（草稿）

行动号召和暂停画面

工具	描述
get_video_ctas	获取视频的行动号召
create_video_cta	为视频创建行动号召
update_video_cta	更新视频上的现有行动号召
delete_video_cta	从视频中删除行动号召
get_video_pause_screens	获取视频的暂停画面
create_video_pause_screen	为视频添加暂停画面（草稿）
update_video_pause_screen	更新视频上的暂停画面（草稿）
delete_video_pause_screen	从视频中移除暂停画面

缩略图

工具	描述
get_video_thumbnail	获取缩略图图片 URL
set_video_thumbnail_from_url	使用公开图片 URL 设置视频缩略图
set_video_thumbnail_from_frame	使用视频中的某一帧设置缩略图
delete_video_thumbnail	移除自定义缩略图并恢复默认缩略图

文件夹和设置模板

工具	描述
list_folders	列出视频文件夹
create_folder	创建视频文件夹，也可将其嵌套在另一个文件夹下
rename_folder	重命名视频文件夹
list_settings_templates	列出设置模板
create_settings_template	根据视频当前设置创建设置模板
update_settings_template	更新设置模板（重命名、修改描述或根据视频重新生成快照）
delete_settings_template	删除设置模板
apply_settings_template	将可复用的播放器设置模板应用到视频

上传

工具	描述
upload_video_from_url	从远程 URL 上传视频
get_video_upload_url	获取用于上传本地文件的签名 URL
validate_upload	完成直接视频上传

账户

工具	描述
get_api_usage	获取当前 API 使用量和配额
list_connections	列出已连接到账户的应用
revoke_connection	断开某个应用或你自己的连接

选项

npx @vidalytics/mcp install [flags]

  --client <names>   Configure only these clients, comma-separated
                     (claude-cli, claude-desktop, windsurf, cursor)
  --all              Configure all known clients, even if not detected
  --config <path>    Also configure a custom config file (repeatable)
  --force            Re-apply even if already configured
  --yes              Skip prompts (configure detected clients)

在交互式终端中不带任何标志运行，可获取要配置的客户端清单（自动检测到的客户端会预先选中；按空格键切换，按回车键确认）。--client cursor,windsurf 可执行相同选择，但无需交互。

--config 标志可重复使用，以指定多个文件。目标文件必须符合 Claude Desktop、Cursor 和 Windsurf 使用的 { "mcpServers": {} } 格式；这对于 Zed 等不受支持的客户端或安装了 MCP 插件的 VS Code 很有用。

故障排除

遇到授权问题，或需要重新授权？ 重置 mcp-remote 缓存在 主目录中的凭据，然后重启客户端：

操作系统	命令
macOS / Linux	rm -rf ~/.mcp-auth
Windows (CMD)	rd /s /q "%USERPROFILE%\.mcp-auth"
Windows (PowerShell)	Remove-Item -Recurse -Force "$HOME\.mcp-auth"

MCP Registry

此服务以 com.vidalytics/mcp 的名称发布在官方 MCP Registry 上。这是一个远程（streamable-http）服务，因此支持 Registry 的 MCP 客户端可以直接连接到：

https://api.vidalytics.com/public/v1/mcp

无需 API 密钥或环境变量——首次使用时通过 OAuth 进行授权。

要求

• Node.js 18+
• Vidalytics 账户

许可证

MIT