YouTube Knowledge MCP

一个模型上下文协议（MCP）服务器，让 AI 助手能够从 YouTube 视频中搜索、分析和提取知识。适用于 Claude Desktop、Claude Code、Claude.ai、Cursor 以及任何兼容 MCP 的客户端。

支持 本地（stdio）和 远程（Streamable HTTP）两种传输方式。

功能

查找与阅读

• 按关键词搜索视频和频道

• 从播放列表或频道获取视频

• 视频、频道和播放列表元数据、章节及热门评论

• 带时间戳的转录文本，可按时间范围或章节切片，并设有上限，以免三个小时的视频淹没你的上下文

• 在转录文本中搜索，并返回可在精确时刻打开视频的 ?t= 链接

• 批量工具：一次获取多个视频的转录文本，或生成整个播放列表的摘要

提取以用于剪辑

• 剪辑时间范围，无需下载整个视频，可按时间戳或章节名称精确剪切或按关键帧剪切

• 音频片段，支持 mp3、m4a、wav、flac 或 opus 格式

• 帧捕获，可在任意时间戳截取，无需下载文件

• 字幕导出，支持 SRT、WebVTT 或纯文本，适用于 Premiere、Resolve 或 CapCut

• 完整下载，提供画质预设

保留你学到的内容（本地模式）

• 保存摘要和技能笔记到本地库

• 回读这些内容，并通过全文排序搜索全部内容

• 添加标签、重新标记和删除

为频道构建一个大脑（本地模式）

• 通读整个频道，构建一个可搜索的带时间戳段落语料库，支持任何字幕语言，可恢复且可安全中断——第二次运行会从上次停止处继续，并获取新上传的视频

• 询问创作者关于任何话题说过什么，覆盖每个视频，并返回相关时刻本身，附带的链接可在该处打开视频

• 衡量频道：多少内容可读、其上传节奏、说话速率，以及跨视频重复的短语

• 在语料库旁保留一份书面档案，并附上可引用的段落作为依据

为持续运行而构建

• WebVTT 由 W3C 参考实现解析，而非手写匹配器

• 类型明确、可操作的用户提示——例如显示“no captions in en, try: fr, es, de”，而不是满屏的 yt-dlp stderr

• 每次调用 yt-dlp 都有超时、指数退避重试和并发限制

• check_health 诊断 yt-dlp 和 ffmpeg 是否缺失或版本过旧

• 每个工具都提供结构化输出，此外还有 MCP 资源、提示和补全

Related MCP server: YouTube Translate MCP

前提条件

• Node.js 22+

• yt-dlp — 每个工具都需要。brew install yt-dlp（macOS）或 pip install -U yt-dlp

• ffmpeg — 下载、片段提取和帧捕获需要。其他功能无需它也能运行。

运行 check_health 工具以确认两者均已安装且为最新版本。yt-dlp 版本过旧是大多数无法解释的失败的最常见原因，因为 YouTube 变动频繁；yt-dlp -U 可修复其中的大多数问题。

安装

通过 npm（推荐）

npm install -g youtube-knowledge-mcp

通过 npx（无需安装）

直接使用 npx 进行配置（参见配置部分）。

从源码安装

git clone https://github.com/teobouancheau/youtube-knowledge-mcp.git
cd youtube-knowledge-mcp
npm install
npm run build

配置

本地（stdio）——Claude Desktop、Claude Code、Cursor

使用 npx 快速开始

{
  "mcpServers": {
    "youtube-knowledge": {
      "command": "npx",
      "args": ["-y", "youtube-knowledge-mcp"]
    }
  }
}

使用全局安装

npm install -g youtube-knowledge-mcp

{
  "mcpServers": {
    "youtube-knowledge": {
      "command": "youtube-knowledge-mcp"
    }
  }
}

配置文件位置

更新配置后，请重启你的客户端。

远程（HTTP）——Claude.ai、Claude Mobile、自定义连接器

服务器通过 Claude 的官方连接器支持 Streamable HTTP 传输，用于远程访问。

每个远程设置都是你自己的部署。 按照设计，不存在可让连接器指向的共享实例：每次调用都会调用 yt-dlp，因此，如果一台主机为他人流量提供服务，YouTube 会对该主机进行速率限制，影响所有人。下面的按钮可将此仓库部署到你自己的 Render 账户中，大约两分钟，无需克隆任何内容。

自托管

npm run build
npm run start:http

服务器监听 PORT（默认 3000）。可通过设置 PORT 环境变量来更改。

Docker

docker build -t youtube-knowledge-mcp .

TOKEN=$(openssl rand -hex 32) && echo "MCP_AUTH_TOKEN=$TOKEN"
docker run -p 3000:10000 -e MCP_AUTH_TOKEN="$TOKEN" youtube-knowledge-mcp

该令牌会被打印出来，因为没有任何其他方式会打印它：服务器只会记录需要令牌，而从不记录其值。请将其作为 Authorization: Bearer $TOKEN 发送。

该镜像设置 PORT=10000 并将其暴露；你可以将其发布到任何喜欢的主机端口。构建在镜像内部完成，因此无需先在本地执行 npm run build。

部署到 Render

该按钮会在此仓库中打开 Render 的 Blueprint 流程，针对 render.yaml，它会构建 Docker 镜像、将健康检查指向 /health，并为你生成 MCP_AUTH_TOKEN。无需 fork、无需克隆、无需填写设置——该服务属于你，位于你的账户中。

1. 点击按钮并确认。Render 会构建镜像并部署它。

2. 打开服务的 环境 选项卡，复制生成的 MCP_AUTH_TOKEN。HTTP 传输会拒绝没有该令牌的每个请求，因此 URL 泄露也不会导致服务器开放。

3. 将 https://<your-service>.onrender.com/mcp 添加为自定义连接器，并使用 Authorization: Bearer <token>。

服务创建后值得做的一件事：将 MCP_ALLOWED_HOSTS 设置为你服务的主机名（<your-service>.onrender.com）。它无法从 Blueprint 中填写，因为主机名直到服务创建后才存在，并且它会拒绝以任何其他名称到达的请求。

你的实例不会跟随此仓库。Blueprint 设置了 autoDeployTrigger: off，因为自动部署会在此处推送的代码在未经你事先阅读的情况下于你的账户中、在你的令牌下运行。要获取更新版本，请使用服务上的 手动部署。

免费计划会在无活动后休眠，因此暂停后的第一次调用需要等待冷启动。任何付费计划都可消除这种情况。

通过 Claude.ai 连接

1. 转到 设置 > 连接器

2. 点击 添加自定义连接器

3. 输入你的服务器 URL（例如 https://your-app.onrender.com/mcp）

4. 如果设置了 MCP_AUTH_TOKEN，请添加 Authorization: Bearer <token> 请求头

5. 点击 添加

MCP 工具

共 33 个工具。其中 14 个只读工具可在两种传输方式下工作；19 个会接触文件系统的工具仅在本地（stdio）模式下注册，因此远程部署无法访问主机的磁盘。

每个工具都返回人类可读的文本和类型化的结构化输出，并将失败报告为可操作的消息——[NO_CAPTIONS] No "en" captions are available for this video. Call get_transcript again with one of: fr, es, de.

发现 — 远程 + 本地

转录文本 — 远程 + 本地

format: "timestamped" 会为每行添加 [MM:SS] 前缀——当你需要引用或链接到某个时刻时，请使用它。maxChars 与 offset 结合使用，可以分段读取长转录文本，而不是一次性返回超过 100,000 个令牌。

提取以用于剪辑 — 仅本地

片段使用 --download-sections 剪切，因此只获取覆盖窗口的字节范围，而不是整个文件。preciseCuts（默认 true）会精确剪切到请求的时间点；将其设为 false 可获得更快的关键帧对齐剪切。所有这些都需要 ffmpeg。

知识库 — 仅本地

频道大脑 — 仅本地

build_brain 是唯一需要访问网络的工具。其余工具都从磁盘上已有的内容解析频道，因此它们可以离线工作，且调用不消耗任何资源。

一个大脑只包含一种字幕语言；传入 language 可读取另一种语言，并为每种语言分别构建大脑。

since 和 minDurationSeconds 描述的是大脑本身，而不仅仅是传入它们的调用。它们每次都会被重新应用，因此缩小范围会丢弃被排除视频的片段，扩大范围则会重新读取这些片段——这就是为什么 build_brain 被标注为破坏性操作。一个视频是否符合条件取决于已经记录的日期和长度，所以在有新的内容需要获取之前，改变主意不会消耗任何请求。这些值来自每个视频自身的元数据，绝不来自猜测：一个扁平的频道列表根本不包含发布日期。

build_brain 还会进行修复。如果片段文件丢失或被截断，它无法再解释的视频会在下一次调用时被重新读取，而不是像已处理过一样被永久跳过。

提示词

你的客户端可以直接调用的可复用工作流：summarize_video、extract_skill、compare_videos、research_topic、channel_deep_dive、clip_from_quote（找短语，然后剪出该短语周围的片段），以及——仅本地——review_library、create_brain（构建频道的语料库，然后据此撰写其配置文件）和 ask_creator（严格基于某个大脑回答问题，并附带引用）。

资源

• youtube://transcript/{videoId} — 带时间戳的字幕文本，首次读取时获取并缓存

• youtube://library/{videoId}/{summary|skill} — 已保存的笔记（仅本地，且可枚举）

• youtube://brain/{channelId}/{manifest|profile} — 频道大脑所覆盖的内容，或从中写入的配置文件（仅本地，且可枚举）

错误代码

失败会以结果内部的形式报告，以便模型能够读取并从中恢复；每个失败都带有代码前缀，并附有下一步操作。

环境变量

全部可选。

知识库存储

内容存储在 ~/.youtube-knowledge/：

~/.youtube-knowledge/
├── transcripts/          # Cached timestamped transcripts
│   └── {video_id}.{lang}.json
├── library/              # Saved notes
│   └── {video_id}/
│       ├── metadata.json
│       ├── summary.md
│       └── skill.md
├── brains/               # Channel brains
│   └── {channel_id}/
│       ├── manifest.json # What the brain covers, and where a build stopped
│       ├── chunks.json   # The timestamped passages
│       └── profile.md    # The written account, if one was saved
├── downloads/            # Full downloads
├── clips/                # Extracted clips
├── frames/               # Captured stills
├── subtitles/            # Exported SRT / VTT / TXT
├── index.json            # Library index
└── search-index.json     # Full-text search index

默认情况下，字幕缓存 30 天；向任何字幕工具传递 refresh: true 可绕过缓存，或设置 YOUTUBE_MCP_TRANSCRIPT_TTL_MS。

所有写入文件的工具都将其输出限制在主目录内，如果 outputDir 指向其他位置，则会被拒绝。

使用示例

找到某个瞬间并引用它

"Find where this video talks about rate limiting and give me the timestamp:
 https://youtube.com/watch?v=..."

search_transcript 返回每个匹配项，并附带一个链接，可在该秒打开视频，从而可以对说法进行核实，而不是盲目信任。

找到某个瞬间并剪辑它

"Find where she says 'the real bottleneck was the database' and cut me a
 30-second clip around it"

search_transcript 定位瞬间，extract_clip 进行剪辑。只下载覆盖该剪辑的字节范围。

读取长视频的某个片段

"Summarize just the 'Benchmarks' chapter of this 3-hour podcast"

get_chapters 找到片段，然后使用带 chapter: "Benchmarks" 的 get_transcript 只读取该部分，而不是全部内容。

低成本概览播放列表

"What does this 40-video course cover, and which three videos should I watch?"

digest_playlist 一次调用即可返回每个视频的元数据和章节。

为剪辑准备素材

"Pull these four moments as separate clips and export the subtitles as SRT"

extract_clips 一次调用即可全部剪辑这四个；export_subtitles 会写出编辑器可以导入的文件。

构建并查询知识库

"Summarize this video and save it to my library tagged 'databases'"
"What have I saved about connection pooling?"

save_to_library 保存它；search_library 使用全文排序搜索所有已保存的内容。

为创作者构建大脑

"Build a brain for @Fireship, then tell me everything they've said about Rust"

build_brain 将频道读取为带时间戳的片段——中断它并再次调用即可继续。ask_brain 然后根据实际所说的内容进行回答，返回这些瞬间本身，以便每项声明都可以对照视频进行核实。一个月后再次运行 build_brain，它只会读取新的上传内容。

测试

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report, with thresholds enforced

测试套件直接覆盖纯逻辑，通过 MCP 客户端在内存传输上驱动真实服务器，对真实临时文件系统上的知识库进行测试，并对工具清单进行快照，从而对公共接口的任何更改都会以可审查的差异形式呈现。

开发

npm run dev        # Watch mode
npm run build      # Build for production
npm run rebuild    # Clean and rebuild
npm start          # Run server (stdio)
npm run start:http # Run server (HTTP)
npm run validate   # Typecheck + lint + format check + test

CI 在 Node 22 和 24 上对每次推送和拉取请求运行相同的检查，然后以真实的 MCP 客户端启动构建后的服务器以验证清单。

贡献

欢迎贡献——有关项目结构、编码标准以及如何添加工具，请参阅 CONTRIBUTING.md。

安全

除非设置 MCP_AUTH_TOKEN，否则 HTTP 传输未经过身份验证。在将其暴露到 localhost 之外以及报告漏洞之前，请参阅 SECURITY.md。

许可证

MIT 许可证 - 详见 LICENSE。

致谢

• yt-dlp 用于 YouTube 提取

• Anthropic 用于 Model Context Protocol