Youtube

@pipeworx/youtube

YouTube 视频、频道、评论和转录文本：搜索视频和频道，获取包含观看数和点赞数的元数据、评论串以及视频字幕文本。

属于 Pipeworx — 一个将 AI Agent 连接到 1763+ 个实时数据源的 MCP 网关。这是独立的非官方集成，与上游提供商无关，未获其认可，也并非由其发布。

工具

• yt_search(query, type?, …) — 搜索符合关键词的视频、频道或播放列表。
• yt_video_details(video_id) — 标题、描述、时长、观看数／点赞数／评论数、标签。
• yt_channel_details(channel_id | username) — 订阅者数、视频数和观看数。
• yt_channel_videos(channel_id, …) — 频道最近上传的视频。
• yt_video_comments(video_id, …) — 顶层评论串。
• yt_video_transcript(video_id, lang?, start_seconds?, max_chars?) — 视频的字幕，包括带时间戳的片段及合并后的文本、字幕语言，以及字幕是否为自动生成。接受纯 ID 或 youtube.com / youtu.be URL。长视频会分页：响应中包含 truncated 和 next_start_seconds；将后者传回 start_seconds。

身份验证

• yt_video_transcript — 无需密钥。
• 其他所有工具 — 仅使用自备密钥：从 Google Cloud Console 获取 YouTube Data API v3 密钥，并通过 _apiKey 传入。Pipeworx 不提供共享密钥。

数据源

• https://www.googleapis.com/youtube/v3 — Data API（除转录文本外的所有工具）。
• https://www.youtube.com/youtubei/v1/player — YouTube 自身的播放器端点，使用 ANDROID 客户端上下文调用；随后通过 fmt=json3 获取其 captionTracks[].baseUrl 中的字幕。

转录文本的上游接口并不稳定。 这是一个未公开文档的端点，并非已发布的 API；YouTube 可以随时更改。以下是截至 2026-10-09 的已知情况（从 Worker 进行边缘探测，fleet #2846）：

• WEB 观看页会列出相同的字幕轨道，但其 URL 带有 exp=xpe，且需要 PO token：直接请求时会返回 200，但响应正文为 0 字节。这会导致静默的空转录文本，因此不使用 WEB 路由。ANDROID 客户端的字幕轨道 URL 无需 PO token 即可获取。
• YouTube 有时会向数据中心 IP 返回 LOGIN_REQUIRED，提示“登录以确认您不是机器人”。此情况按请求而非按视频发生：通过实时网关连续调用 10 次，单次尝试中有 7 次遇到此问题，随后相同的视频又能正常访问。因此，该工具会先尝试 ANDROID 客户端，再尝试 IOS（两者提供的字幕 URL 都无需 PO token；ANDROID_VR 不符合条件，它在每次探测中都会遇到机器人验证）。如果两者都被拒绝，工具会打开公开观看页。如果页面显示视频可播放且没有字幕轨道，则返回 captions_unavailable。否则会携带页面提供的访客 ID 和 Cookie 重试这两个客户端。只有四次尝试全部被拒绝后，调用才会以 upstream_down 失败，并说明 YouTube 正在阻止我们的服务器。工具绝不会返回空转录文本。部分出口 IP 请求观看页时会收到 429，此时会跳过该页面。
• 翻译（&tlang=）从数据中心 IP 请求时会返回 429，因此如果视频没有所需语言的字幕轨道，工具会拒绝请求并返回 captions_unavailable（列出视频现有的字幕轨道），而不会进行机器翻译。
• 没有字幕轨道的视频会以 captions_unavailable 失败。私有、已移除或被地区屏蔽的视频会以 not_found 失败，并附上 YouTube 自身给出的原因。

如果所有视频都开始无法获取，首先检查 src/index.ts 中的 ANDROID clientVersion — YouTube 会弃用旧的客户端版本。

此时不会改用出口中继作为备用方案。已于 2026-10-09 进行测量并排除该方案（fleet #2877）。 这看似是显而易见的下一步，但其表现远不如现有方案。我们从中继自身的 Supabase edge 基础设施上的临时函数，对 www.youtube.com 进行了探测：

转录所需环节	通过中继	住宅网络控制
POST /youtubei/v1/player	403，10/10 — Google 的“抱歉……您的计算机或网络可能正在发送自动查询”页面，每次调用都是完全相同的 1,103 字节，覆盖 5 个不同视频	200 OK，3/3，2 个字幕轨道
GET /watch?v=	200，5/5，存在访客 ID	—
GET /api/timedtext（已签名）	200，3/3，79,833 字节 — 与住宅网络返回的逐字节相同	200，79,833 字节

因此，拦截严格限定在一个端点——innertube 播放器调用—— 而且目前这也是 Cloudflare 上唯一失败的环节。中继有 100% 的概率拒绝该调用；Cloudflare 出口有 40% 的概率拒绝（2026-10-09，跨 10 个视频的 20 次实时 yt_video_transcript 调用中有 8 次失败）。把播放器调用改由中继转发，会让工具从部分可用变成永远不可用，这就是为什么 www.youtube.com 被有意排除在中继的 ALLOWED_HOSTS 之外（那里有一条说明）。通过中继的两个环节确实能正常工作，并不是需要帮助的环节。

测量 40% 的失败率需要谨慎：网关会缓存工具响应，因此重复使用相同参数进行探测，测出的结果会好得离谱。对同样的 10 个视频进行未破坏缓存的测试，得分为 14/16；每次调用都改变 max_chars 以绕过缓存后，得分为 12/20。改变某个参数，否则测到的只是缓存。

实际上还剩下的方案都尚未尝试：住宅/移动代理（需要付费，因此由 Bruce 决定）、用于生成 PO-token 的工具，让 WEB 路由的 exp=xpe URL 不再返回 0 字节；或者接受 40% 的成功率，让错误消息中的重试建议作为解决方案。

快速开始

添加到您的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "youtube": {
      "url": "https://gateway.pipeworx.io/youtube/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/youtube/mcp 上的 tools/list 会返回上表中的工具，以及共享的 Pipeworx 元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 和网关级工具集中的其他工具。因此，您看到的工具数量会多于此表所列：单个工具包端点目前会列出大约 30 个共享工具，以及该工具包自身的工具。连接的 initialize 响应会说明其确切范围，是了解当天情况的权威依据。

这是有意为之，并非意外的多路复用。这些元工具让限定范围的连接也能回答此工具包未覆盖的问题——通过 ask_pipeworx 跨整个目录路由——无需添加第二个 MCP 服务。目前无法挂载不含这些工具的工具包端点；如果额外的架构定义占用的上下文比路由带来的价值还多，请连接一次完整网关，而不是连接多个工具包端点。

也可以连接到完整的 Pipeworx 网关，直接列出所有工具包的工具，而不只是当前这个工具包的：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和相同的 1763+ 个数据源。唯一的区别是直接列出哪个工具包的工具；从任一端点都可以通过 ask_pipeworx 访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

此工具包需要您自己的 API 密钥（_apiKey）——我们不会代为提供，因此这里没有无需密钥即可运行的 curl 命令。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/yt_search。查找工具：使用 {"query":"..."} 向 POST https://gateway.pipeworx.io/v1/tools/search_packs 发送请求。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需经由网关往返：

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-youtube"]
    }
  }
}

也可以直接运行，确认它能启动：

npx -y @pipeworx/mcp-youtube

它通过 stdin/stdout 使用 MCP 通信，并对 initialize/tools/list/tools/call 作出响应，仅包含此工具包的工具——不包含上方网关连接所添加的任何共享元工具。来源相同，工具相同，不经过 ask_pipeworx 路由。

与 ask_pipeworx 搭配使用

你可以用自然语言提问，而不是直接调用工具 —— 这适用于上面的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Youtube data" })

网关会选择合适的工具并自动填写参数。

更多

• 文档和指南
• pipeworx.io

许可证

MIT