YouTube字幕MCP服务器

Name: YouTube字幕MCP服务器
Author: hancengiz

作者：hancengiz2 星标更新：2025-11-05

安装使用来源：spider==github.com

项目介绍

YouTube Transcript MCP Server

这是一个用于从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：从源代码安装

克隆此仓库：

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

安装依赖项：

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一起工作的示例：

提取字幕以总结视频：

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

分析视频中的特定主题：

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

获取不同语言的字幕：

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

提取不含时间戳的引用（针对长视频）：
```
从这个视频中获取不含时间戳的字幕：https://www.youtube.com/watch?v=LCEmiRjPEtQ
```
注意：这个60分钟的视频不带时间戳生成约19k令牌，而带时间戳则生成约30k。

研究和内容创作：

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

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

节省90%的上下文空间！

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

快速示例

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

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

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

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

youtube-transcript-analyzer代理

这个专门的代理：

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

使用场景

内容总结：从长达一小时的技术演讲中提取关键学习点（例如，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）。请使用分页、过滤或限制参数减少响应大小。

解决方案：

禁用时间戳（推荐用于长视频）：
```
从这个视频中获取不含时间戳的字幕：https://www.youtube.com/watch?v=VIDEO_ID
```
这通常可以将响应大小减少20-30%，使大多数视频符合限制。
请求较短的视频（通常60分钟以下的视频即使启用时间戳也能工作）
分块处理：对于非常长的视频，您可能需要编程方式处理字幕数据，而不是通过MCP工具

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

https://www.youtube.com/watch?v=LCEmiRjPEtQ（60分钟的技术演讲）
启用时间戳：约30,000令牌 ❌（超出25k限制）
不启用时间戳：约19,000令牌 ✅（完美工作）

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

故障排除

服务器未出现在Claude Code中

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

“无字幕可用”错误

并非所有YouTube视频都有字幕
有些视频只有某些语言的自动生成字幕
私人或受限视频无法访问
尝试检查YouTube上视频是否启用了字幕

语言未找到

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

无效URL错误

确保您使用的是有效的YouTube URL格式
视频ID应恰好为11个字符
确保视频存在并且是公开可访问的

开发

要修改或扩展服务器：

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

测试

运行测试套件：

npm test

这将验证：

符合Claude API的JSON模式
工具注册和列表
字幕抓取功能
错误处理
URL解析

许可证

MIT

作者

由Cengiz Han创建

贡献

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