星战科技xingzhan.cloud
返回市场
YouTube字幕MCP服务器

YouTube字幕MCP服务器

作者：hancengiz2 星标更新：2025-11-05
安装使用来源：spider==github.com

项目介绍

YouTube Transcript MCP Server

npm 版本 npm 下载量

这是一个用于从YouTube视频中提取字幕的Model Context Protocol (MCP)服务器，专为Claude Code设计。该服务器允许您轻松地提取视频字幕，无需手动下载或复制内容，非常适合分析视频内容、总结演讲或从教育视频中提取信息。

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

安装后，服务器将全局可用。您可以通过运行以下命令进行配置：

# 该包将安装在您的全局node_modules中
# 通常位于：/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
  1. 安装依赖项：
npm install

配置

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

方案1：使用Claude Code CLI（最简单）

推荐：机器范围安装

# 为所有项目（机器范围）添加MCP服务器
claude mcp add --scope user youtube-transcript npx @fabriqa.ai/youtube-transcript-mcp@latest

理解作用域选项：

Claude Code支持三种MCP服务器配置作用域：

  • --scope user（推荐） - 机器范围

    • 在所有项目和目录中可用
    • 配置一次，处处可用
    • 适用于跨不同项目的常用工具

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

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

  • --scope project - 明确项目

    • 用于特定项目的配置

示例用法：

# 机器范围（推荐用于youtube-transcript）
claude mcp add --scope user youtube-transcript npx @fabriqa.ai/youtube-transcript-mcp@latest

# 项目特定（如果您偏好）
claude mcp add --scope local youtube-transcript npx @fabriqa.ai/youtube-transcript-mcp@latest

# 或使用便捷脚本
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）

示例：

你能从这个链接获取字幕吗？https://www.youtube.com/watch?v=LCEmiRjPEtQ

从这个视频中获取不含时间戳的字幕：https://youtu.be/LCEmiRjPEtQ

总结这个Andrej Karpathy演讲的关键学习点：https://www.youtube.com/watch?v=LCEmiRjPEtQ

2. get-transcript-languages

检查视频可用的字幕语言。

参数：

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

示例：

这个链接的视频有哪些可用的字幕语言？https://www.youtube.com/watch?v=LCEmiRjPEtQ

示例工作流程

这是如何使用此MCP服务器与Claude Code一起工作的示例：

  1. 提取字幕以总结视频：

    给我这个Andrej Karpathy演讲的关键学习点：https://www.youtube.com/watch?v=LCEmiRjPEtQ

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

    从这个视频中获取字幕并提取所有关于“LLM”和“代理”的提及：https://www.youtube.com/watch?v=LCEmiRjPEtQ

  3. 获取不同语言的字幕：

    这个链接的视频有哪些可用的字幕语言？https://www.youtube.com/watch?v=LCEmiRjPEtQ

  4. 提取不含时间戳的引用（针对长视频）：

    从这个视频中获取不含时间戳的字幕：https://www.youtube.com/watch?v=LCEmiRjPEtQ

    注意：这个60分钟的视频不带时间戳生成约19k令牌，而带时间戳则生成约30k。

  5. 研究和内容创作：

    从这个视频中获取3个关于部分自主应用程序的引用：https://www.youtube.com/watch?v=LCEmiRjPEtQ

高级：使用Claude Code子代理提高上下文效率

节省90%的上下文空间！

Claude Code支持专门的子代理，可以在隔离的上下文中分析YouTube视频，只返回分析结果到您的主要对话。这意味着您可以分析许多视频而不占用上下文窗口的大段字幕。

快速示例

与其这样做（填满您的上下文超过20k令牌）：

获取这个视频的字幕并分析：[URL]

这样做（上下文只有约2k令牌）：

使用子代理来分析这个视频：[URL]

youtube-transcript-analyzer代理

这个专门的代理：

  • ✅ 在其自己的隔离上下文中获取字幕
  • ✅ 彻底分析内容
  • ✅ 只返回分析结果给您
  • ✅ 让您在一个会话中分析10多个视频
  • ✅ 保持您的上下文干净且专注

更多信息

📖 完整的Claude Code子代理指南

该指南包括：

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

适合： 研究人员、内容创作者、学生以及需要在一个会话中分析多个视频的人。

使用场景

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

优点

  • 节省时间：无需观看整个视频即可获取视频内容
  • 上下文效率：只需提取您需要的文字内容
  • 灵活格式：选择是否包含时间戳
  • 多语言：当有可用时，访问不同语言的字幕
  • 易于集成：通过简单的URL接口与Claude Code集成

技术细节

  • 使用@modelcontextprotocol/sdk构建
  • 使用自建的YouTube字幕库（yt-lib/）
  • 字幕抓取零外部依赖（使用原生fetch API）
  • 作为本地Node.js进程运行，通过stdio通信
  • 支持所有带有可用字幕/字幕的YouTube视频
  • 直接集成YouTube的Innertube API，确保可靠地访问字幕

局限性

MCP协议令牌限制

MCP（模型上下文协议）基础设施有一个25,000令牌响应限制，以保护Claude的上下文窗口并防止性能问题。此限制由MCP协议层施加，而非YouTube或此工具。

这意味着：

  • 非常长的视频字幕（通常是60分钟以上）启用时间戳可能会超出此限制
  • 字幕成功从YouTube抓取，但如果太大，MCP将阻止响应

症状：

错误：MCP工具“get-transcript”响应（30131令牌）超过
最大允许令牌数（25000）。请使用分页、过滤或限制参数减少响应大小。

解决方案：

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

    从这个视频中获取不含时间戳的字幕：https://www.youtube.com/watch?v=VIDEO_ID

    这通常可以将响应大小减少20-30%，使大多数视频符合限制。

  2. 请求较短的视频（通常60分钟以下的视频即使启用时间戳也能工作）

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

现实世界示例（Andrej Karpathy的演讲）：

解决办法：只需询问“获取不含时间戳的字幕”即可。

故障排除

服务器未出现在Claude Code中

  1. 验证配置文件中的路径是否正确
  2. 确保已安装Node.js并在PATH中
  3. 检查依赖项是否已安装：npm install
  4. 完全重启Claude Code
  5. 检查Claude Code日志是否有任何错误消息

“无字幕可用”错误

  • 并非所有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服务器。