Youtube Transcript Mcp

YouTube Transcript MCP 服务

一个 Model Context Protocol (MCP) 服务，可为 Claude Code 获取 YouTube 视频的文字稿。借助此服务，你可以轻松提取视频文字稿，无需手动下载或复制内容，非常适合分析视频内容、总结演讲或从教育视频中提取信息。

• 关于此 MCP 服务的博客文章 又添一块拼图：为我的学习钢铁侠战衣加入 YouTube 分析
• npm 包： @fabriqa.ai/youtube-transcript-mcp
• 作者：Cengiz Han

功能

• 获取视频文字稿：提取任何提供字幕的 YouTube 视频的完整文字稿
• 支持多种 URL 格式：支持所有常见的 YouTube URL 格式（youtube.com、youtu.be 等）
• 时间戳支持：可在文字稿输出中包含或排除时间戳
• 语言选择：可在支持时请求指定语言的文字稿
• 错误处理：妥善处理没有文字稿的视频或无效 URL
• 高效使用上下文：仅获取文字稿，不加载不必要的视频元数据

安装

选项 A：通过 npm 安装（推荐）

npm install -g @fabriqa.ai/youtube-transcript-mcp

安装后，该服务将全局可用。你可以运行以下命令进行配置：

# The package will be installed in your global node_modules
# Typically: /usr/local/lib/node_modules/@fabriqa.ai/youtube-transcript-mcp

选项 B：从源代码安装

1. 克隆此仓库：

git clone https://github.com/hancengiz/youtube-transcript-mcp.git
cd youtube-transcript-mcp

2. 安装依赖项：

npm install

配置

如果通过 npm 安装（推荐）：

选项 1：使用 Claude Code CLI（最简单）

推荐：整台计算机安装

# Add the MCP server for all projects (machine-wide)
claude mcp add --scope user youtube-transcript npx @fabriqa.ai/youtube-transcript-mcp@latest

了解作用域选项：

Claude Code 为 MCP 服务提供三种配置作用域：

• --scope user（推荐）- 整台计算机

  • 在所有项目和目录中均可用
  • 配置一次，处处可用
  • 非常适合在不同项目中经常使用的工具

• --scope local（默认）- 针对特定项目

  • 仅在当前目录及其子目录中可用
  • 适用于特定项目的 MCP 服务
  • 每个项目都必须单独配置

• --scope project - 显式指定项目

  • 用于特定项目配置

使用示例：

# Machine-wide (recommended for youtube-transcript)
claude mcp add --scope user youtube-transcript npx @fabriqa.ai/youtube-transcript-mcp@latest

# Project-specific (if you prefer)
claude mcp add --scope local youtube-transcript npx @fabriqa.ai/youtube-transcript-mcp@latest

# Or use the convenience script
npx @fabriqa.ai/youtube-transcript-mcp/update-config.js

选项 2：手动配置

添加到 ~/.claude.json：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "@fabriqa.ai/youtube-transcript-mcp@latest"
      ]
    }
  }
}

这会使用 npx 自动运行全局安装的包，无需指定路径。

快速设置脚本（可选）：

通过 npm 安装后，你可以使用附带的配置脚本自动更新 ~/.claude.json：

npx @fabriqa.ai/youtube-transcript-mcp/update-config.js

如果从源代码安装，则运行：

node update-config.js

这会使用 npx 自动添加 MCP 服务，使其在整台计算机上的所有项目中均可用。

手动配置：

对于 Claude Desktop，编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "@fabriqa.ai/youtube-transcript-mcp@latest"
      ]
    }
  }
}

使用方法

完成配置后，重启 Claude Code。以下工具将可用：

1. get-transcript

获取 YouTube 视频的转录文本。

参数：

• url（必填）：YouTube 视频 URL 或视频 ID
• lang（可选）：转录文本的语言代码（例如 'en'、'es'、'fr'）。默认：视频的默认语言
• include_timestamps（可选）：在输出中包含时间戳。默认：true

支持的 URL 格式：

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://m.youtube.com/watch?v=VIDEO_ID
• VIDEO_ID（仅包含 11 个字符的视频 ID）

示例：

Can you get the transcript from https://www.youtube.com/watch?v=LCEmiRjPEtQ?

Get the transcript from this video without timestamps: https://youtu.be/LCEmiRjPEtQ

Summarize the key learnings from this Andrej Karpathy talk: https://www.youtube.com/watch?v=LCEmiRjPEtQ

2. get-transcript-languages

查看视频有哪些可用的转录语言。

参数：

• url（必填）：YouTube 视频 URL 或视频 ID

示例：

What transcript languages are available for https://www.youtube.com/watch?v=LCEmiRjPEtQ?

示例工作流

以下是使用 Claude Code 和此 MCP 服务的示例：

1. 提取转录文本以总结视频：

   Give me the key learnings from this Andrej Karpathy talk: https://www.youtube.com/watch?v=LCEmiRjPEtQ
   

2. 分析视频中的特定主题：

   Get the transcript from https://www.youtube.com/watch?v=LCEmiRjPEtQ and extract all mentions of "LLM" and "agents"
   

3. 获取不同语言的转录文本：

   What transcript languages are available for https://www.youtube.com/watch?v=LCEmiRjPEtQ?
   

4. 提取不带时间戳的引述（适用于长视频）：

   Get the transcript without timestamps from this video: https://www.youtube.com/watch?v=LCEmiRjPEtQ
   

   注意：这段 60 分钟的视频在不带时间戳时会生成约 19k 个 token，而带时间戳时约为 30k 个 token。

5. 研究与内容创作：

   Get 3 key quotes from Andrej Karpathy about partial autonomy apps from https://www.youtube.com/watch?v=LCEmiRjPEtQ
   

进阶：使用 Claude Code 子 Agent 提高上下文利用率

分析视频时节省 90% 的上下文！

Claude Code 支持专用子 Agent，可在隔离的上下文中分析 YouTube 视频，并仅将分析结果返回到主对话中。这意味着你可以分析许多视频，而不会因大量转录文本占满上下文窗口。

快速示例

不要这样做（会占用上下文中的 20k+ 个 token）：

Get the transcript and analyze this video: [URL]

而要这样做（上下文中仅占用约 2k 个 token）：

Use sub-agent to analyze this video: [URL]

youtube-transcript-analyzer Agent

这个专用 Agent 可以：

• ✅ 在自己的隔离上下文中获取转录文本
• ✅ 全面分析内容
• ✅ 仅向你返回分析结果
• ✅ 让你在一次会话中分析 10 个以上的视频
• ✅ 保持上下文整洁、聚焦

了解更多

📖 Claude Code 子 Agent 完整指南

该指南包含：

• 子 Agent 如何节省上下文（附示例）
• youtube-transcript-analyzer Agent 的完整设置说明
• 可直接复制的配置文件
• 实际使用示例和工作流
• 高效分析多个视频的进阶技巧

适用对象： 研究人员、内容创作者、学生，以及任何需要在一次会话中分析多个视频的人。

使用场景

• 内容摘要：从长达一小时的技术演讲中提取关键知识点（例如，Andrej Karpathy 的《AI 时代的软件》）
• 研究：无需观看，即可分析会议演讲、学术讲座和教育内容
• 内容创作：从视频内容中获取准确的引述和参考资料，用于博客文章或其他文章
• 学习与教育：快速回顾讲座内容，提取主要概念和示例
• 无障碍访问：将视频内容转换为可搜索、易读的文本格式
• 访谈分析：从播客访谈和小组讨论中提取引述和见解
• 技术文档：从教程视频中提取代码示例和技术说明

优势

• 节省时间：无需观看完整视频即可获取视频内容
• 提高上下文利用率：只提取所需的文本内容
• 格式灵活：可选择是否包含时间戳
• 多语言支持：在有可用转录文本时，获取不同语言的转录文本
• 轻松集成：为 Claude Code 提供简单的基于 URL 的接口

技术详情

• 使用 @modelcontextprotocol/sdk 构建
• 使用自定义构建的 YouTube 字幕库（yt-lib/）
• 获取字幕时无外部依赖（使用原生 fetch API）
• 作为本地 Node.js 进程运行，通过 stdio 通信
• 支持所有提供字幕的 YouTube 视频
• 直接集成 YouTube 的 Innertube API，以可靠地获取字幕

限制

MCP 协议令牌限制

MCP（Model Context Protocol）基础设施设有 25,000 个令牌的响应限制，用于保护 Claude 的上下文窗口并避免性能问题。此限制由 MCP 协议层施加，与 YouTube 或此工具无关。

这意味着：

• 启用时间戳时，很长的视频字幕（通常为 60 分钟以上）可能会超出此限制
• 虽然能成功从 YouTube 获取字幕，但如果响应过大，MCP 会阻止返回

症状：

Error: MCP tool "get-transcript" response (30131 tokens) exceeds
maximum allowed tokens (25000). Please use pagination, filtering,
or limit parameters to reduce the response size.

解决方案：

1. 禁用时间戳（长视频推荐）：

   Get the transcript without timestamps from https://www.youtube.com/watch?v=VIDEO_ID
   

   这样通常可将响应大小缩小 20-30%，让大多数视频都能符合限制。

2. 请求较短的视频（通常，60 分钟以内的视频启用时间戳也能正常处理）

3. 分块处理：对于很长的视频，可能需要以编程方式处理字幕数据，而不是通过 MCP 工具处理

真实示例（Andrej Karpathy 的演讲）：

• https://www.youtube.com/watch?v=LCEmiRjPEtQ（60 分钟的技术演讲）
• 启用时间戳：约 30,000 个令牌 ❌（超出 25k 限制）
• 禁用时间戳：约 19,000 个令牌 ✅（可正常处理）

变通方法：对于长视频，只需询问“获取不含时间戳的字幕”。

故障排除

服务器未显示在 Claude Code 中

1. 确认配置文件中的路径正确
2. 确保已安装 Node.js，且其路径已添加到 PATH
3. 检查是否已安装依赖项：npm install
4. 完全重启 Claude Code
5. 检查 Claude Code 日志中是否有错误消息

“No transcript available” 错误

• 并非所有 YouTube 视频都有字幕
• 有些视频仅提供特定语言的自动生成字幕
• 无法访问私人或受限视频
• 尝试检查 YouTube 上是否已启用视频字幕

找不到语言

• 使用 get-transcript-languages 工具检查可用语言
• 常见语言代码：'en'、'es'、'fr'、'de'、'ja'、'ko'、'pt'、'ru'、'zh' 等
• 并非所有视频都提供所有语言的字幕

URL 无效错误

• 确保使用有效的 YouTube URL 格式
• 视频 ID 必须正好为 11 个字符
• 确认视频存在且可公开访问

开发

要修改或扩展服务：

1. 编辑 index.js 以添加新工具或修改现有工具
2. 更新 ListToolsRequestSchema 处理程序以注册新工具
3. 在 CallToolRequestSchema 处理程序中添加对应的处理程序
4. 使用 npm test 测试更改
5. 重启服务（重启 Claude Code）以测试更改

测试

运行测试套件：

npm test

此操作将验证：

• 是否符合 Claude API 的 JSON 架构
• 工具注册和列表
• 字幕获取功能
• 错误处理
• URL 解析

许可证

MIT

作者

由 Cengiz Han 创建

参与贡献

欢迎提交问题或拉取请求，以改进此 MCP 服务。