youtube-transcript-mcp

一个 MCP 服务器，让编码代理能够读取和搜索 YouTube 视频字幕。无需 API 密钥、无需 Google 账户、无需注册任何东西。它通过 YouTube 的公共端点获取字幕，并额外提供原始字幕转储所没有的一项功能：章节摘要。

这最初是我自己使用的一个小工具。我经常遇到包含 YouTube 链接的对话，需要知道视频实际说了什么，而反复粘贴字幕浪费了大量时间。后来它变成了一个可复用的服务器，任何基于 Model Context Protocol 运行的程序都可以直接调用。

功能

四个工具。

• get_transcript(video_url_or_id, languages=["en"], include_timestamps=False) 获取完整字幕并返回纯文本。它接受完整的 YouTube URL（watch?v=、youtu.be、/embed/、/shorts/、/live/）或裸的 11 位视频 ID。

• get_video_metadata(video_url_or_id) 通过 YouTube 的免认证 oEmbed 端点返回标题、频道名称、频道 URL 和缩略图。它刻意不返回发布日期或完整描述，因为那些需要官方的 Data API 密钥，而这里的重点恰恰是你不需要密钥。

• search_transcript(video_url_or_id, query, languages=["en"]) 查找与关键词或短语匹配的字幕片段，不区分大小写，每个片段都带有 [mm:ss] 时间戳，以便模型能够指出视频中某句话出现的位置。

• summarize_chapters(video_url_or_id, gap_seconds=4.0, min_chunk_seconds=45.0, languages=["en"]) 将字幕按自然停顿切分为粗略的时间分块，并返回这些分块，这样代理就可以逐段总结，而不是一次性吞下整个巨大的文本块。这是一个启发式方法，并非 YouTube 真实的章节数据。

所有工具都返回纯字符串，包括错误信息（例如"Error: captions are disabled for this video"）。不会有异常暴露给调用代理，也不会泄漏任何堆栈跟踪。

Related MCP server: youtube-mcp

刻意不提供的功能

• 不适用于字幕已禁用的视频、私密或不可用的视频，以及没有字幕的直播流。它会明确说明原因，而不是猜测。

• 不依赖 YouTube Data API。没有它就无法获取发布日期或完整描述，这是设计使然。

• 不做缓存。对同一视频的两次调用会两次重新获取。对于该工具的实际用途来说没问题。如果你将来需要大规模使用，可以自行添加缓存。

安装

需要 Python 3.11+ 和 uv。

uv sync

独立运行以确认它能正常启动：

uv run server.py

它会一直等待 MCP stdio 输入，因此在客户端连接之前看起来像是没有任何反应。这是正常现象。按 Ctrl+C 退出。

注册到 MCP 客户端

将其添加到客户端的 MCP 设置中。服务器通过 stdio 调用，因此配置就是一条命令行。以 Claude CLI 为例：

claude mcp add youtube-transcript -- uv --directory /absolute/path/to/youtube-transcript-mcp run server.py

或者在 JSON 配置中：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/youtube-transcript-mcp", "run", "server.py"]
    }
  }
}

来之不易的经验教训

• 只有带字幕（自动生成或手动上传）的视频才能工作。没有字幕的视频会返回明确的错误，这是一个刻意的选择：空结果看起来像是静默失败，而错误信息则明确指出了问题。

• 语言列表很重要。languages=["en"] 会在存在英文字幕轨时获取英文字幕。如果某个频道只上传其他语言的内容，请传入对应的语言代码。

• 将 mcp>=1.28.1 固定下来，但保持在 2.0 以下。mcp 2.x 重命名了 mcp.server.fastmcp，导入会在服务器启动时静默失败。你需要的是能真正加载的那个版本。

许可证

MIT。参见 LICENSE。