YouTube Transcripts, Search & Summaries

YouTube Transcripts MCP 服务

托管版本（无需设置）： apify.com/parallelstudio/youtube-transcripts-mcp。使用你的 Apify token，将任意 MCP 客户端连接到 https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp，按调用付费。本仓库提供开源代码；你也可以在本地运行：npm install && npm run build && node dist/index.js（stdio）。

为你的 AI Agent 提供 YouTube 转录文本、搜索、章节和摘要。此 MCP 服务可获取任意公开 YouTube 视频的字幕（纯文本、带时间戳的片段或 SRT）及其元数据。它还可以搜索 YouTube、返回章节，并生成结构化的摘录式摘要，其中每个要点都链接到对应内容所在的时间点。

它适用于 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf，以及任何支持通过 Streamable HTTP 使用 MCP 的其他客户端。你不需要 YouTube API 密钥或 Google 账号。服务端不会运行大模型，因此你无需为他人的 token 付费。

你可以用它做什么

• 加快研究。“总结这段 2 小时的播客，并列出 10 个带时间戳的关键要点。”
• **回答关于视频的问题。**加载转录文本，让你的 Agent 引用并标注准确的时间点。
• **浏览长视频。**获取创作者添加的章节。如果视频没有章节，则获取根据转录文本生成的主题片段。
• **查找来源。**按上传日期、时长、排序方式和“有字幕”筛选 YouTube 搜索结果，然后获取最佳结果的转录文本。
• **改编内容。**导出 SRT 字幕、撰写节目说明，或根据演讲内容起草博客文章；可使用任意字幕语言或 YouTube 的机器翻译。

工具

工具	功能	关键参数
get_transcript	返回转录文本及元数据：标题、频道、时长、观看次数、发布日期、类别、可用的字幕语言，以及返回的字幕轨道是否为自动生成。输出格式可以是纯文本、带 [m:ss] 时间戳的段落、{start, duration, text} 片段或 SRT。也可以使用 YouTube 机器翻译。	video、languages（优先级列表，默认为 ["en"]）、format（text | segments | srt）、include_timestamps、translate_to、allow_auto_generated、fallback_to_any_language、max_chars
search_videos	通过网站使用的同一 InnerTube 搜索 API 搜索 YouTube。返回视频 ID、标题、频道、时长、观看次数、相对发布时间、简介摘要、缩略图、直播标记和徽章。会自动获取更多页面，直至达到 limit。	query、limit（1–50）、upload_date（hour…year）、duration（short <4 分钟、medium 4–20 分钟、long >20 分钟）、sort_by、features（例如 subtitles、live、hd、creative_commons）、hl、gl
get_video_chapters	返回带起止时间和深层链接的章节。使用创作者在简介中添加的章节或 YouTube 章节标记。如果没有章节，则根据转录文本生成主题片段，并以各片段的独特关键词和代表性句子为其命名。	video、source（auto | description | transcript）、languages、target_chapters
summarize_transcript	无需大模型即可生成结构化的摘录式摘要，包括 TL;DR、去重后的关键要点、关键词和关键短语、每章的要点列表以及重要引言。每个条目都带有时间戳和 …&t=123s 链接。	video、max_points（1–30，默认为 8）、languages、bullets_per_chapter、max_quotes、keyword_limit

video 可接受 11 个字符的视频 ID（dQw4w9WgXcQ）或任意 YouTube URL：watch?v=、youtu.be/、/shorts/、/embed/、/live/，以及 m. 和 music. 域名，还有 youtube-nocookie.com。

所有工具均为只读。

错误代码

失败时会返回 MCP 工具错误（isError: true）。文本以 Error (<CODE>): … 开头，structuredContent.error 包含 { code, message, retryable, details }，因此你的 Agent 可以根据代码采取相应操作，而不必解析消息：

代码	含义
INVALID_VIDEO_ID / INVALID_INPUT	视频 ID、URL 或其他参数无效
VIDEO_UNAVAILABLE	视频已被删除、从未存在，或 ID 错误
VIDEO_PRIVATE	视频为私密视频
AGE_RESTRICTED	YouTube 要求使用已登录账号（年龄限制）
VIDEO_UNPLAYABLE	仅限会员观看、受地区限制、即将开始的直播等（details.reason 中包含 YouTube 提供的文本）
TRANSCRIPTS_DISABLED	视频没有任何字幕
NO_TRANSCRIPT_FOUND	请求的语言均不存在，且 fallback_to_any_language 为 false。details.available 列出了实际存在的字幕轨道
TRANSLATION_UNAVAILABLE	YouTube 无法将此字幕轨道翻译为 translate_to 指定的语言
NO_CHAPTERS	请求了 source: "description"，但说明中没有章节列表
REQUEST_BLOCKED	即使服务已轮换代理会话，YouTube 仍阻止了请求（HTTP 429、reCAPTCHA 或“确认你不是机器人”）。retryable: true
PO_TOKEN_REQUIRED / EMPTY_TRANSCRIPT	YouTube 提供的字幕 URL 需要 PO token，或字幕文件为空
UPSTREAM_ERROR / INTERNAL_ERROR	超时、5xx 响应或意外的响应格式

定价

此 Actor 采用按事件计费。仅成功的工具调用会产生工具事件费用。调用失败时不会收取工具事件费用，无论是参数验证失败、视频为私密视频或没有字幕，还是 YouTube 阻止了请求。Apify 还会在每次服务实例启动时收取标准的 Actor 启动事件费用（每 GB 内存 $0.00005，至少计一个事件）。按默认的 512 MB 待机内存计算，每次启动费用为 $0.00005；一个运行中的实例在进入空闲状态前可以处理多次调用。此 Actor 的 Pricing 选项卡是当前价格的权威来源。

事件	价格	收费时机	数量
transcript	$0.005	每次成功调用 get_transcript	每次调用 1 次，无论视频时长或格式
search	$0.003	每次成功调用 search_videos	每次调用 1 次（最多 50 个结果，包括自动获取的额外页面）
chapters	$0.008	每次成功调用 get_video_chapters	每次调用 1 次，章节来自说明或根据字幕推导
summary	$0.015	每次成功调用 summarize_transcript	每次调用 1 次。内部获取的字幕不会另外按 transcript 收费

搜索返回 0 个结果仍视为成功调用，并按 1 个 search 事件收费。

连接 MCP 客户端

端点（Streamable HTTP）：

https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp

通过发送 Authorization: Bearer <APIFY_TOKEN>，使用你的 Apify API token 进行身份验证。

Cursor（~/.cursor/mcp.json 或 .cursor/mcp.json）

{
  "mcpServers": {
    "youtube-transcripts": {
      "url": "https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp",
      "headers": {
        "Authorization": "Bearer <APIFY_TOKEN>"
      }
    }
  }
}

Windsurf（~/.codeium/windsurf/mcp_config.json）

{
  "mcpServers": {
    "youtube-transcripts": {
      "serverUrl": "https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp",
      "headers": {
        "Authorization": "Bearer <APIFY_TOKEN>"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）

Claude Desktop 的配置文件只能启动本地（stdio）服务，因此请使用 mcp-remote（需要 Node.js）连接到托管端点。以下配置也适用于任何仅支持 stdio 的其他客户端：

{
  "mcpServers": {
    "youtube-transcripts": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp",
        "--header", "Authorization: Bearer ${APIFY_TOKEN}"
      ],
      "env": { "APIFY_TOKEN": "<APIFY_TOKEN>" }
    }
  }
}

无法发送标头的客户端

Apify 也接受将 token 作为 token 查询参数，因此仅接受 URL 的客户端可以使用：

https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp?token=<APIFY_TOKEN>

如果客户端支持，请优先使用 Authorization 标头：URL 中的 token 可能会出现在日志中。范围受限的 Apify token 可在 token 泄露时限制损失。

Claude Code

claude mcp add --transport http youtube-transcripts \
  https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp \
  --header "Authorization: Bearer $APIFY_TOKEN"

VS Code（.vscode/mcp.json）

{
  "servers": {
    "youtube-transcripts": {
      "type": "http",
      "url": "https://parallelstudio--youtube-transcripts-mcp.apify.actor/mcp",
      "headers": { "Authorization": "Bearer ${input:apifyToken}" }
    }
  },
  "inputs": [{ "id": "apifyToken", "type": "promptString", "description": "Apify API token", "password": true }]
}

示例提示词

• “获取 https://youtu.be/aircAruvnKk 的文字稿，并解释其中关于梯度下降的部分，注明时间戳。”
• “搜索去年以来关于 Rust 异步的演讲，时长超过 20 分钟且带字幕，然后总结排名前 3 的演讲。”
• “列出这场 3 小时直播的章节。如果没有章节，就按主题拆分。”
• “将这段视频的德语字幕导出为 SRT。如果没有德语字幕轨道，就翻译字幕。”

示例输出

以下摘录来自测试套件中捆绑的示例视频（每次调用和响应请参阅 demo/transcript.md）。

get_transcript { "video": "kM3pLz8QwT0", "format": "segments", "include_timestamps": true }（已删节）：

{
  "video": {
    "id": "kM3pLz8QwT0",
    "url": "https://www.youtube.com/watch?v=kM3pLz8QwT0",
    "title": "How Solar Panels Actually Work (Explained Simply)",
    "channel": "Bright Circuits",
    "durationSeconds": 552,
    "duration": "9:12",
    "viewCount": 1843291,
    "publishDate": "2025-03-14T07:00:12-07:00",
    "category": "Education",
    "isLive": false
  },
  "transcript": {
    "language": "en",
    "languageName": "English",
    "autoGenerated": false,
    "translatedFrom": null,
    "matchedPreference": true,
    "format": "segments",
    "segmentCount": 128,
    "wordCount": 870,
    "truncated": false,
    "segments": [
      { "start": 0, "duration": 4.116, "time": "0:00", "text": "Hey everyone, welcome back to Bright Circuits." },
      { "start": 4.2, "duration": 4.116, "time": "0:04", "text": "Today we're answering a question I get" }
    ]
  },
  "availableLanguages": [
    { "languageCode": "en", "languageName": "English", "autoGenerated": false, "translatable": true },
    { "languageCode": "es", "languageName": "Spanish", "autoGenerated": false, "translatable": true },
    { "languageCode": "en", "languageName": "English", "autoGenerated": true, "translatable": true }
  ],
  "translationLanguagesCount": 18
}

get_video_chapters 用于一段没有创作者章节的视频（仅自动字幕）。章节根据文字稿生成：

#	开始时间	标题（辨识性关键词）
1	0:00	面粉、加水、克数
2	2:00	水解、克数、温热
3	4:11	拉伸、折叠、一次发酵
4	5:52	冷藏、侧面、表面
5	9:34	盖子
6	10:30	冷却、切开、内部组织

summarize_transcript { "video": "kM3pLz8QwT0", "max_points": 6 }（摘录）：

• 要点： [2:32] 当能量足够的光子击中硅时，它会撞出一个电子，并留下一个空穴。 · [5:09] 太阳能电池板产生直流电，但家庭和电网使用的是交流电。 · [6:52] 家用电池会在白天储存多余的太阳能，以便你在晚上使用……
• 关键词： 面板、电池片、逆变器、光子、太阳能、能源、电池、电流、太阳能电池板、电子
• 章节要点使用创作者的 7 个章节（“硅太阳能电池内部”“逆变器与电网”……），每章包含 2 个要点。
• 引语： “逆变器会将直流电转换为交流电，使其与电网的电压和频率完全匹配。” [5:18]

工作原理

文字稿

服务获取文字稿的方式与常用的 Python 库 youtube-transcript-api 相同：

1. 加载观看页面。如果 YouTube 显示欧盟 Cookie 同意页面，则接受。如果出现 reCAPTCHA 页面，则报告为 REQUEST_BLOCKED。该页面还会提供 InnerTube API 密钥、发布日期、类别和任何章节标记。
2. 使用 ANDROID 客户端上下文调用 InnerTube player API。该 API 会返回视频详情和 captionTracks。可播放状态会映射到上述错误代码：私密、年龄受限、不可用、无法播放，或“请确认你不是机器人”。
3. 选择字幕轨道。按优先级依次检查每种首选语言，手动字幕优先于自动生成字幕，精确代码匹配优先于基础语言匹配（en-GB → en）。然后下载 timedtext 文件。服务会解析 srv1 XML、srv3 XML 和 json3。

针对同一视频的 3 个请求都会通过同一个代理会话，因为 YouTube 会将字幕 URL 签发给发起请求的 IP 地址。

绕过 YouTube 的 IP 封锁

YouTube 会封锁大多数云 IP。在 Apify 的可行性测试中，直接请求成功获取了 5 个测试视频中的 1 个。使用 Apify 数据中心代理后，5 个中有 4 个可用，第 5 个视频则根本没有文字稿。因此，在 Apify 平台上，此服务会通过 Apify Proxy（默认使用数据中心代理）转发每个 YouTube 请求，并使用粘性会话和 undici ProxyAgent。当 YouTube 封锁某个会话时（429、验证码、机器人检查、字幕文件为空、网络错误），服务会丢弃该会话并更换 IP 重试；每次调用最多使用 5 个会话。状态正常的会话会留给后续调用复用。

从转录文本生成章节

如果视频没有创作者章节，服务会采用类似 TextTiling 的方式对转录文本进行分段：

1. 将转录文本拆分为 20–60 秒的时间块，并为每个时间块构建 TF-IDF 向量。
2. 在每两个时间块之间的间隙处，比较前两个时间块与后两个时间块的词汇（余弦相似度）。相似度骤降表示主题发生了变化。
3. 保留差异最大的间隙，同时确保章节长度不低于最短要求。然后，按时间窗口回退策略拆分仍然明显长于平均长度的章节。
4. 将每个边界调整到最近的句子起始处。用能区分该章节与其他章节的关键词为章节命名，并附上最具代表性的句子。

无需大模型的摘要

1. 构建句子。带标点的字幕会按标点拆分。自动生成的字幕没有标点，因此会逐词重新计时，并在话语标记（“so”“now”“next”……）和停顿处切分为较短的片段。[Music] 这类标签会被移除。
2. 使用 TextRank 对句子排序：在由 TF-IDF 余弦相似度加权的图上运行 PageRank。过短的片段会被降低权重。
3. 使用 MMR（最大边际相关性）选取关键点、章节要点和引文，避免重复近似内容。然后按时间顺序重新排列。
4. 根据频率为关键词评分，并使用以 1 分钟时间窗口计算的 IDF 加权。已被选定双词词组涵盖的单个词会被剔除。

该方法确定、透明且速度快：获取转录文本后，几毫秒即可完成。由于引用的都是讲者自己的原话，因此不会产生幻觉。

局限性

• 仅支持公开视频字幕。 私人视频、仅限会员观看的视频和年龄限制视频会返回明确的错误代码。服务绝不会登录。
• 效果取决于字幕质量。 自动生成的字幕没有标点，并且可能存在一些识别错误。摘要和生成的章节可以处理这些情况，但创作者提供的字幕能生成质量更好的句子。
• 采用抽取式摘要，而非生成式摘要。 摘要引用转录文本中的句子，不会改述。停用词列表和词干提取针对英语进行了调整。其他语言仍可使用，但关键词会稍显嘈杂。
• 搜索结果仅包含视频。 不包括频道、播放列表和 Shorts 栏目，也不包括“其他用户还观看了”推荐。相对日期（“3 weeks ago”）会按 YouTube 显示的内容原样传递。
• 使用非官方端点。 InnerTube 和 timedtext 是 YouTube 自有应用使用的 API，但没有文档说明，且可能发生变化。服务会采用退避策略重试并轮换代理。响应会在内存中缓存 10 分钟。
• 直播。 正在进行的直播通常要等结束后才会有转录文本。

常见问题

我需要 YouTube Data API 密钥或 Google 账号吗？ 不需要。调用此托管服务只需 Apify 账号和令牌。

支持哪些语言？ 支持 YouTube 提供字幕的任何语言。传入优先语言列表，例如 ["de", "en"]。如果列表中的语言都没有字幕，除非你将 fallback_to_any_language: false，否则会返回最合适的可用字幕轨道，并附带说明。使用 translate_to 时，YouTube 会对字幕轨道进行机器翻译。

视频时长有限制吗？ 没有固定限制。无论转录文本有多长，每份转录文本都会计为一个 transcript 事件。对于特别长的视频，请使用 max_chars 或 summarize_transcript，以控制 Agent 的上下文长度。

为什么我收到了 REQUEST_BLOCKED？ YouTube 拒绝了服务为此次调用尝试使用的所有代理 IP。这通常是暂时的，请稍等片刻后重试。被拦截的调用不会收费。

会存储数据吗？ 不会。服务是无状态的，只保留短暂的内存缓存。它不会向数据集或键值存储写入任何内容。

可以自托管吗？ 可以。请参见下文。住宅 IP 通常可以直接访问 YouTube。在云服务器上，请设置 YT_PROXY_URL。

自托管与开发

npm install
npm run build
npm start              # MCP over stdio
npm run start:http     # Streamable HTTP at http://127.0.0.1:3000/mcp (GET / and /health = readiness)
npm test               # build + unit tests + MCP smoke test, all offline against recorded fixtures

环境变量	默认值	用途
PORT / HOST	3000 / 127.0.0.1	HTTP 绑定（--http）；也可使用 --port、--host
YT_PROXY_URL	(未设置)	使用自己的一个或多个代理：以逗号分隔的 http://user:pass@host:port URL，每个会话使用一个固定 URL，按轮询方式分配
YT_PROXY	(未设置)	off 可禁用代理，即使在 Apify 上也是如此
YT_PROXY_GROUPS / YT_PROXY_COUNTRY	datacenter / any	Apify Proxy 的组（例如 RESIDENTIAL）以及平台上的国家/地区代码
YT_PROXY_ATTEMPTS	5	返回 REQUEST_BLOCKED 前每次调用尝试的代理会话数
YT_FIXTURES	(未设置)	使用 fixture 目录响应所有 YouTube 请求（离线模式，供测试使用）
HTTP_TIMEOUT_MS	8000	每次请求的超时时间（代理出口卡住时会切换，不会等待）
HTTP_MAX_RETRIES	2	仅对直接（未使用代理的）连接进行 5xx/超时的原地重试；使用代理的调用则会切换会话
YT_KEEP_ALIVE_MS	60000	两次调用之间代理隧道的空闲保持时间
YT_SLOW_SESSION_MS	6000	如果代理会话的操作耗时更长，该会话就会被弃用，以便下次调用使用新的 IP
CACHE_TTL_MS	600000	内存缓存 TTL（0 表示禁用）
BILLING	(未设置)；Docker 镜像中为 apify	apify 启用按事件计费的 Actor.charge()；log 仅将费用打印到 stderr

在 Apify 上（Standby 模式）。 设置 APIFY_IS_AT_HOME 后，服务会调用 Actor.init()、强制使用 HTTP 模式，并监听 0.0.0.0:$ACTOR_WEB_SERVER_PORT。GET / 会响应 Standby 就绪探测，MCP 则通过 /mcp 提供服务。YouTube 流量会经过 Apify Proxy。HTTP 服务本身没有身份验证：在 Apify 上，平台会使用你的 API token 对请求进行身份验证。如果你在 localhost 之外自托管，请将其置于身份验证代理之后。

测试

• 单元测试（test/unit/*.test.mjs，node --test）使用手工制作的 fixture 运行，这些 fixture 模拟真实的 YouTube 响应：ANDROID 播放器 JSON、srv1/json3 定时字幕文本、带有 continuations 和 shelves 的 WEB 搜索页面、包括 reCAPTCHA 页面的观看页面，以及所有错误状态。测试涵盖解析、字幕轨道选择、描述和派生章节、TextRank 和摘要、搜索 params 编码、错误映射以及代理会话轮换。
• MCP 冒烟测试（test/smoke.mjs）使用 YT_FIXTURES 通过 stdio 启动服务，列出工具，调用每个工具（包括错误路径），检查计费仅针对成功的调用，检查 HTTP 模式和就绪探测，并写入 demo/transcript.{json,md}。
• 实时远程测试（test/live-remote.mjs，不属于 npm test）针对已部署的 Standby URL 运行：MCP_URL=… APIFY_TOKEN=… node test/live-remote.mjs。
• npm run fixtures 会通过 scripts/make-fixtures.mjs 重新生成 test/fixtures/。

.actor/        actor.json (Standby, /mcp), input_schema.json (empty), output_schema.json (MCP endpoint)
Dockerfile     apify/actor-node:20, multi-stage TypeScript build, BILLING=apify
src/
  index.ts       entry: stdio or stateless Streamable HTTP; Apify Standby wiring
  server.ts      MCP tool registrations (zod schemas, error payloads, billing)
  youtube.ts     watch page → InnerTube player (ANDROID) → timedtext; track selection; error mapping
  transcript.ts  srv1/srv3/json3 parsing; text / SRT formatting
  search.ts      InnerTube search, protobuf filter params, continuation paging
  chapters.ts    description chapter parser; TextTiling-style derived chapters
  text.ts        tokenizer, stemmer, sentences, TF-IDF, TextRank, keywords
  summary.ts     extractive summary (key points, chapter bullets, quotes, stats)
  http.ts        timeouts/retries, proxy sessions + rotation, fixture mode
  proxy.ts       Apify Proxy / YT_PROXY_URL selection
  fixtures.ts    offline fixture resolver
  billing.ts     chargeEvent() → Actor.charge() when BILLING=apify
  util.ts        error codes, cache, id/URL parsing, time helpers

许可证

MIT