vidlens-mcp

您的 AI 能阅读网页。
现在也能观看视频。

npx vidlens-mcp setup

• **研究视频：**搜索、转录、比较并引用 YouTube 和公开社交视频。
• **构建本地资料库：**导入一次，即可搜索转录文本、评论、画面和 OCR，无需再次获取同一视频。
• **检查视觉证据：**在视觉画廊和结构化客户端输出中查找准确画面、时间戳、匹配原因和来源。

VidLens 是一款 MCP 服务，可让您的 AI Agent 观察视频，包括 YouTube、X、TikTok、Instagram、其他视频页面或您磁盘上的文件。粘贴链接并提出问题即可。VidLens 会读取转录文本、查看画面，并给出附有可核对时间戳的答案。它摄取的所有内容都会存入您自己机器上的资料库，因此您的 Agent 无需重复观看同一视频。

无需 API 密钥即可开始使用。适用于 Claude Desktop、Claude Code 和 Codex。具备相应能力的客户端可将 VidLens 的结构化结果转换为原生图表、卡片、表格和可视化报告，并呈现在自身的响应界面中。

观看 VidLens 实际演示

▶ 在 YouTube 上观看 1:46 演示

---

试用

设置好 VidLens 后，将以下任意内容粘贴到您的 AI 客户端中：

“在 YouTube 上搜索 M5 Max MacBook Pro 评测。评测者有哪些共识？又在哪些方面存在分歧？”

VidLens 会搜索视频、阅读各位评测者的转录文本，并结合来源和时间戳总结共识与分歧。

“转录并总结这段视频：https://x.com/username/status/123...”

单个公开的 X、Instagram 或 TikTok 视频 URL 通常完全不需要 API 密钥。VidLens 会获取视频、转录内容并保存转录文本，以便您稍后在当前会话或未来的任意会话中提出后续问题。

“找出这段视频中展示基准测试图表的画面。”

视觉搜索会查看屏幕上的内容——幻灯片、图表、白板、产品镜头等——并在本地浏览器画廊中显示实际画面及其时间戳，而不是只给出文字猜测。

原生客户端呈现

VidLens 返回可移植的结构化证据：来源、时间戳、评分、OCR、描述、出处和局限。Codex、Claude 及其他功能强大的客户端可以将这些证据组合成各自原生的图表、对比卡片、表格和可视化报告。

呈现由客户端负责，而不是由内嵌的 VidLens UI 负责。若要检查提取的帧，searchVisualContent 也可以打开浏览器图库。

---

工作原理

视频来源从左侧输入。VidLens 会通过可用的路径采集视频——配置了密钥时使用 YouTube API、yt-dlp 或直接提取网页内容——并将结果存储在本地库中，包括转录文本、帧和嵌入。你的 Agent 可以通过任何 MCP 客户端查询该库。

内置两项诚信保障：

• 回退机制，而非失败。 每个 YouTube 数据工具都会尝试多种路径后再放弃，因此即使缺少密钥或配额耗尽，也会平稳降级，而不会中断运行。
• 响应附带出处。 工具响应会报告数据由哪条路径提供，以及是否存在部分数据。不会静默降级。

所有内容都存储在磁盘上的一个目录中。无需外部数据库，也无需 Docker。复制该目录即可备份；删除它即可重新开始。

---

安装

设置向导（推荐）

npx vidlens-mcp setup

向导会检测 Claude Desktop、Claude Code 和 Codex，检查 VidLens 所需的本地依赖，并提供一个简单的选择：

• 免费设置（推荐）： 无需 API 密钥。YouTube 搜索、转录文本、元数据和本地库都可以立即使用。
• 增强设置： 按需逐项添加可选 API、语音转文本、网络搜索或浏览器 Cookie。按 Enter 跳过不需要的项目；已保存的值会保留，且不会显示。

按 Enter 选择免费设置；需要增强功能时，可随时运行 npx vidlens-mcp setup --enhanced。对于 Claude Code，设置过程还会将 VidLens 注册到用户 MCP 注册表、安装共享的 VidLens 工作流技能，并在可行时通过 claude mcp list 检查结果。

手动配置

Claude Desktop — 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "vidlens-mcp": {
      "command": "npx",
      "args": ["-y", "vidlens-mcp", "serve"]
    }
  }
}

Claude Code — 建议使用向导：

npx vidlens-mcp setup --client claude_code
claude mcp list

如果改为手动配置，请在 ~/.claude.json 中添加相同的 mcpServers.vidlens-mcp 条目。

Codex — 使用设置辅助工具，以便同时注册 MCP 服务和捆绑的 VidLens 技能：

npx vidlens-mcp setup --client codex

重启客户端

完全退出并重新打开 Claude Desktop（按 ⌘Q，而不只是关闭窗口）——MCP 服务会在启动时加载。对于 Claude Code，请在设置完成后启动新会话或运行 /mcp。

从本地检出目录安装

在检出目录中运行 npm install 不会将二进制文件放到你的 PATH 中。请从检出目录运行 npm run setup；如果开发时需要直接使用 vidlens-mcp 命令，也可以运行 npm install -g . / npm link。

---

你的资料库

VidLens 是视频工作的持久化记忆，不是每次会话的临时草稿。你导入的所有内容都会保存在 VIDLENS_DATA_DIR 下的磁盘中：字幕集合、评论集合、已下载的媒体和视觉索引。甚至当前活动集合也会被记住。

一次调用即可回顾。 会话开始时，recallWorkspace 会返回已存储内容的精简摘要，让 Agent 在再次搜索或导入前了解已有内容。工具描述也会向每个客户端传达相同的提醒，因此 Agent 会先检查，而不是重新获取。

通过 URL 或资源键重复使用。 可通过原始 URL 或资源键再次调取已导入社交视频的字幕，无需重新下载或转录。

Agent 共用一个资料库。 所有客户端默认使用同一个数据目录，因此 Claude Desktop、Claude Code 和 Codex 共用一个资料库——在一个客户端导入视频，就能从另一个客户端搜索。

⚠️ 请勿将 VIDLENS_DATA_DIR 放在 Dropbox、iCloud、Google Drive 或任何文件同步文件夹中。 VidLens 使用 SQLite（启用了 WAL），文件同步工具中的实时数据库可能会损坏或产生冲突副本。请将数据目录放在本地磁盘上——默认位置已满足此要求。

---

不止 YouTube

对于 X、Instagram、TikTok 和通用视频页面，VidLens 采用分级能力策略：选择可行的最低成本方式，API 密钥是能力提升选项，而非前置条件。

方式	成本	最适合	处理方式
本地复用	免费	之前导入的任何内容	recallWorkspace 查找已存储的字幕或媒体；不会重新获取
公开直连 URL	免费	单条 X 动态、Instagram 短视频／帖子或 TikTok 视频	yt-dlp 匿名尝试获取规范帖子 URL；没有字幕时，由 ffmpeg 和本地或已配置的 STT 处理媒体
浏览器辅助	使用受支持的宿主时免费	查找或核实帖子，或使用已有的登录会话	客户端的浏览器控制功能捕获规范 URL 和可见元数据，然后将 URL 交给 VidLens
本地文件交接	免费	你获准保存的视频	导入已保存的文件以进行转录和视觉索引
API 增强	按提供商定价	批量、无人值守或可重复的发现	自动选择已配置的 ScrapeCreators、Brave、SerpAPI、YouTube、Gemini 或 OpenAI 能力

三点注意事项，直言不讳：

• 浏览器辅助取决于宿主。 MCP 服务本身不控制浏览器，而是依赖客户端提供的浏览器工具；不同宿主提供的工具也不同。
• 能看到视频不代表能导出视频。 帖子能在浏览器中播放，并不保证媒体可以自动导出。
• 仅支持具体 URL。 VidLens 导入的是具体帖子或视频 URL，绝不导入个人主页、探索页面、话题标签或热门页面。

对于超出普通下载范围的社交媒体和本地视频工作，请安装 ffmpeg（macOS 上运行 brew install ffmpeg）——提取帧、建立视觉索引和 STT 音频分块都需要它。

---

工具——11 个模块，共 47 个

探索——YouTube 发现与研究（1 个）

工具	功能
exploreYouTube	意图感知搜索，支持多查询排序、字幕摘要、结构化基准数据和后台索引。一次调用可替代 5–8 次单独的工具调用。

核心功能 — 视频和频道情报（7）

工具	功能说明
findVideos	按查询词搜索 YouTube，并获取元数据
inspectVideo	深入查看元数据，包括标签、互动数据、语言和类别
inspectChannel	查看频道统计数据、简介和近期上传内容
listChannelCatalog	浏览频道的完整视频库
readTranscript	获取完整文字稿，含时间戳和章节
readComments	查看热门评论及其点赞数和互动数据
expandPlaylist	列出任意播放列表中的所有视频

知识库 — 语义文字稿搜索（7）

工具	功能说明
importPlaylist	为整个播放列表的文字稿建立索引
importVideos	按 URL 或 ID 为指定视频建立索引
searchTranscripts	以自然语言搜索已建立索引的内容
listCollections	浏览已建立索引的集合
setActiveCollection	将搜索范围限定为一个集合
clearActiveCollection	搜索所有集合
removeCollection	删除一个集合及其索引

情感分析与分析（4）

工具	功能说明
measureAudienceSentiment	分析评论情感、主题和风险信号
analyzeVideoSet	比较多个视频的表现
analyzePlaylist	分析播放列表层面的互动数据
buildVideoDossier	对单个视频进行全面深入分析

创作者情报（4）

工具	功能说明
scoreHookPatterns	分析哪些视频开场效果出色
researchTagsAndTitles	提供标签和标题优化建议
compareShortsVsLong	比较短视频与长视频的表现
recommendUploadWindows	推荐最适合发布内容以提升互动的时间

发现与趋势（2）

工具	功能说明
discoverNicheTrends	发现任意主题的发展势头、饱和度和内容缺口
exploreNicheCompetitors	查看频道格局和表现最佳的频道

通用视频来源（5）

工具	功能说明
inspectVideoSource	将 YouTube、X、Instagram、TikTok、通用 URL 和本地文件解析为来源元数据和能力标记
searchVideoSources	搜索 YouTube 原生内容和本地素材；支持通过 ScrapeCreators 搜索 TikTok/Instagram，并可配置 Brave/SerpAPI/DuckDuckGo 作为后备方案
searchSocialTrends	通过 ScrapeCreators 搜索社交平台；返回按排名排列的列表，其中包含互动指标和可导入的 URL（如有）
importVideoSources	将 URL 或本地文件导入本地媒体库，并可选择构建视觉索引或文字稿
transcribeVideoSource	通过原生字幕或配置的 STT 转录 YouTube、社交平台/通用 URL 和本地文件

媒体素材（5）

工具	功能说明
downloadAsset	从任何受支持的来源下载或导入视频、音频或缩略图
listMediaAssets	浏览已存储的媒体文件
removeMediaAsset	清理已下载的素材
extractKeyframes	从视频中提取关键帧
mediaStoreHealth	查看存储用量和诊断信息

视觉搜索与证据（3）

工具	功能说明
indexVisualContent	提取画面；运行 Apple Vision OCR 和特征打印、Gemini 画面描述及 Gemini 语义嵌入
searchVisualContent	按含义和文本搜索画面；返回带时间戳的证据，并可打开外部浏览器图库
findSimilarFrames	使用 Apple Vision 特征打印进行图像到图像的画面相似度搜索

视觉搜索使用独立索引，与文字稿索引分开。每条匹配结果都包含时间戳、来源视频、OCR 文本和视觉描述。MCP 结果中会移除本地画面路径和 file: URL；浏览器图库会在本地读取图像，不会向客户端暴露这些路径。

评论知识库（6）

工具	功能
importComments	为视频评论建立索引，以便搜索
searchComments	以自然语言搜索评论语料
listCommentCollections	浏览评论集合
setActiveCommentCollection	限定评论搜索范围
clearActiveCommentCollection	搜索所有评论集合
removeCommentCollection	删除评论集合

诊断（3）

工具	功能
recallWorkspace	在会话开始时汇总所有已导入内容 — 请先调用，以免重复导入
checkSystemHealth	完整的系统诊断报告
checkImportReadiness	导入内容前进行验证

---

可选 API 密钥

VidLens 无需任何密钥即可运行。添加密钥可提升扩展性和可靠性：

密钥	可解锁的功能	免费？	获取位置
YOUTUBE_API_KEY	更丰富的元数据、评论 API、YouTube API 搜索	受 Google 配额限制	Google Cloud Console → 启用 YouTube Data API v3 → 创建 API 密钥
GEMINI_API_KEY	用于语义搜索和视觉搜索的高质量嵌入向量、帧描述	受服务提供商定价和限制约束	Google AI Studio
OPENAI_API_KEY	可选的转录 STT 服务提供商	付费	OpenAI Platform
SCRAPECREATORS_API_KEY	TikTok、Instagram、Threads、Pinterest、Reddit 的直接社交搜索和热门内容搜索，以及受支持的端点	受服务提供商定价约束	ScrapeCreators
BRAVE_API_KEY / SERPAPI_KEY	用于社交内容和通用 URL 发现的结构化网页搜索	因服务而异	Brave Search API 或 SerpAPI

⚠️ YouTube 和 Gemini 密钥分别来自不同的 Google 服务。 Gemini 密钥无法用于 YouTube API 调用，反之亦然。

# Free setup asks for no keys.
npx vidlens-mcp setup

# Enhanced setup optionally prompts for keys, STT, web search, and cookies.
npx vidlens-mcp setup --enhanced

# Or pass everything non-interactively.
npx vidlens-mcp setup \
  --youtube-api-key YOUR_YOUTUBE_KEY \
  --gemini-api-key YOUR_GEMINI_KEY \
  --stt-provider auto \
  --cookies-from-browser chrome

Cookie 和语音转文本

对于会限制匿名访问频率的平台，向导可以按浏览器配置文件或文件路径保存 Cookie：

npx vidlens-mcp setup --cookies-from-browser chrome --cookies-profile Default
npx vidlens-mcp setup --x-cookies-file /path/to/x-cookies.txt

也可以通过环境变量配置：VIDLENS_COOKIES_FROM_BROWSER、VIDLENS_X_COOKIES_FILE、VIDLENS_INSTAGRAM_COOKIES_FILE、VIDLENS_TIKTOK_COOKIES_FILE。

STT 会自动选择：先使用本地 whisper.cpp，然后是 Gemini，最后是 OpenAI。可通过 VIDLENS_STT_PROVIDER=whisper-cpp|gemini|openai|none|auto 覆盖。向导询问时，对大多数人来说，按 Enter 选择 auto 就是正确选项。

---

CLI

npx vidlens-mcp               # Start MCP server (stdio)
npx vidlens-mcp serve         # Start MCP server (explicit)
npx vidlens-mcp setup         # Configure clients, keys, STT, cookies
npx vidlens-mcp doctor        # Run diagnostics
npx vidlens-mcp doctor --no-live   # Diagnostics without network checks
npx vidlens-mcp update-deps   # Refresh managed yt-dlp and Deno helpers
npx vidlens-mcp version       # Print version

doctor 会检查 Node.js 版本、yt-dlp 是否为最新版本、STT 和网页搜索服务提供商、API 密钥有效性、数据目录健康状况，以及 Claude Desktop、Claude Code 和 Codex 的 MCP 客户端注册情况。

---

要求

要求	状态	说明
Node.js ≥ 22	必需	使用 node:sqlite — 可通过 node --version 检查
yt-dlp	自动安装	在运行 npx vidlens-mcp setup 时下载
ffmpeg + ffprobe	推荐	媒体验证、帧提取、视觉索引和 STT 音频处理都需要
YouTube API 密钥	可选	获取更丰富的元数据和评论
Gemini API 密钥	可选	获取更好的嵌入向量和帧描述
macOS	可选	Apple Vision 提供原生 OCR 和图像相似度功能；配置后，其他平台也可使用 Gemini 描述

---

安全与隐私

• 你的资料库——转录文本、帧、嵌入向量、媒体——均存储在本地，并保留在你的设备上。网络调用只会发送到你查询的来源和配置的 API。
• 设置过程会将已配置的密钥存储在本地 MCP 客户端配置中。建议使用交互式 Enhanced 设置，该方式会在输入密钥时将其隐藏；通过 CLI 标志提供的密钥可能会留在 shell 历史记录中。错误消息会经过密钥脱敏处理，因此工具输出不会回显密钥和 Cookie 路径。
• 获取频道页面和通用 URL 时会拒绝私有、链路本地和环回地址（SSRF 防护）。有意在本地使用时，可通过以下方式绕过：VIDLENS_ALLOW_PRIVATE_URLS=1。

---

故障排查

Claude Desktop 中显示“Tool not found”。 完全退出（⌘Q）并重新打开。MCP 服务仅在启动时加载。

出现“YOUTUBE_API_KEY not configured”警告。 这只是提示，不是错误。VidLens 不配置该密钥也能使用。

出现“API_KEY_SERVICE_BLOCKED”。 该密钥无权调用所请求的 Google 服务。在 Google Cloud Console 中启用 YouTube Data API v3，并在密钥的 API 限制中允许该 API。请根据运行 VidLens 的位置设置适当的应用限制；除非你只是进行简短诊断并会立即重新设置限制，否则不要取消密钥限制。

Gemini 密钥无法用于 YouTube。 它们是两个独立服务，使用不同的密钥。请参阅可选 API 密钥。

社交视频已下载，但视觉分析失败。 安装 ffmpeg，然后重新运行设置：

brew install ffmpeg

npx vidlens-mcp doctor --no-live

downloadAsset 通常无需 ffmpeg 即可获取视频，但 indexVisualContent、extractKeyframes、媒体验证和 STT 音频处理需要 ffmpeg 或 ffprobe。

其他问题：

npx vidlens-mcp doctor

---

许可证

MIT

GitHub · npm · Model Context Protocol

1.5.3 Agent 合约变更

listChannelCatalog 接受有界的 scanLimit 和用于重新发现的 refresh: true。maxResults 限制的是返回的匹配项数量，而非初始上传内容的扫描范围。请检查返回的覆盖范围和格式证据：仅凭时长无法证明短视频是 YouTube Short；对于仅请求 Shorts 或长视频的请求，无法确定格式的内容会被排除。

readTranscript 使用从零开始的 UTF-16 文本偏移量，而非秒数或行数。要获取完整转录文本，请从 mode: "full", offset: 0, limit: 15000 开始，然后根据 longVideoHandling.pagination.nextOffset 继续分页，直到 hasMore 为 false。为避免拆分 Unicode 代理对，页面长度可能会少一个代码单元。如果调用者从代理对中间开始读取，系统会返回实际生效的偏移量。限制值必须是 1,000 到 64,000 之间的整数。如果未明确指定偏移量或限制，对于超过 32,000 个代码单元的完整转录文本，仍会采用已说明的关键时刻回退方案。

现在，原生 MCP 调用会拒绝意外的参数名称和无效的整数分页参数，而不会静默忽略拼写错误。默认情况下，searchVisualContent 和 findSimilarFrames 会返回结构化结果，不会打开浏览器；明确请求 openGallery: true 才会创建并打开图库。客户端审批策略仍然适用。

可选的类型化字段必须省略，不得设为 null。只有当某个工具的架构中包含 dryRun 时，才能传入该参数。基于分类的分析现在会包含格式未知的内容；仅凭时长得出的趋势结果无法确定内容是否属于 Shorts；如果提供方未提供日期或互动数据，比较结果可能不完整。如果缺少比较队列，则不会再虚构百分比建议。