yt-subtitle-mcp

一个 MCP 服务器：优先抓 YouTube 现成字幕，没有字幕才用 Whisper 从音频转录。

转录结果落盘成 Obsidian 友好的 Markdown（frontmatter + 带时间戳章节）， 中文内容可选自动转成简体。

语音识别、字幕解析、繁简转换全部在本地完成，不上传音视频，也不需要 语音识别或翻译服务的 API key。

它做什么

输入一个 YouTube 链接，得到一份可读的转录稿。流程：

YouTube URL
  → 取元数据（含字幕清单、原声语种）
  → ① 有合适字幕？→ 下载 json3/VTT → 解析合并 → 落盘      【秒级，零 CPU】
  → ② 没有 → 下载音频 → 16kHz 单声道 wav
            → faster-whisper（CTranslate2 int8，纯 CPU 可跑）
  → 中文内容 → OpenCC 繁→简（可关）
  → 落盘 <输出目录>/<标题>.md
  → 缓存 <输出目录>/.cache/<videoId>.json

Related MCP server: Hermes YouTube Transcript MCP Server

快速开始

git clone https://github.com/aisahpA/yt-subtitle-mcp.git
cd yt-subtitle-mcp
bash scripts/setup.sh

setup.sh 会建 Python venv、装 faster-whisper / yt-dlp（带浏览器指纹伪装）/ OpenCC、 装 Node 依赖，并做一次自检。不需要 GPU。

首次用某个模型时会自动下载权重（默认 large-v3-turbo，约 1.5GB；small 约 470MB）。 如果 huggingface.co 在你的网络下不可达，默认已配好 hf-mirror.com 镜像。

接入客户端

任何支持 stdio MCP 的客户端都可以，把 server.js 的绝对路径填进去。

{
  "mcpServers": {
    "youtube-subtitle": {
      "command": "node",
      "args": ["/绝对路径/yt-subtitle-mcp/server.js"]
    }
  }
}

{
  "mcp": {
    "youtube-subtitle": {
      "type": "local",
      "command": ["node", "/绝对路径/yt-subtitle-mcp/server.js"],
      "enabled": true,
      "environment": {
        "YTS_SUBTITLE_LANG": "zh",
        "YTS_TO_SIMPLIFIED": "1"
      }
    }
  }
}

- insert:
    - id: mcp-youtube-subtitle
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: youtube
        transport: stdio
        command: node
        args:
          - /绝对路径/yt-subtitle-mcp/server.js
        env:
          YTS_SUBTITLE_LANG: zh
          YTS_TO_SIMPLIFIED: '1'
        # 长视频转录可能几十分钟，默认 60s 必然超时
        toolCallTimeoutMs: 7200000

⚠️ 最重要的一条：MCP 的 stdio transport 不继承父进程环境变量 （官方 SDK 只传 HOME/LOGNAME/PATH/SHELL/TERM/USER）。 所以代理、模型、输出目录等配置必须写在客户端的 env 块里， 写在 shell 的 .zshrc 里不会生效。这是最容易踩的坑。

工具

只暴露一个工具：get_video_transcript。

返回什么

关键点：它不返回全文。一份 20 分钟视频的转录稿轻松几万字，直接塞进上下文 既贵又没必要。返回值是：

{
  "video":     { "title": "...", "uploader": "...", "duration": "5:56", "views": "1571.3万" },
  "transcript": {
    "language": "zh-tw",  "source": "youtube-manual-caption",
    "characters": 1453,   "segments": 31,
    "fromCache": false,   "truncated": false,
    "convertedToSimplified": true
  },
  "savedTo":     "/…/transcripts/How to sound smart….md",
  "preview":     "有听见什么吗？答案是「没有」……",
  "summaryHint": "完整正文（1453 字）在 savedTo 指向的 Markdown 里……",
  "description": "视频简介（最多 1500 字）"
}

• savedTo 才是正文所在。 preview 只用来判断"这份稿子对不对"， truncated: true 表示 preview 被截断过。

• transcript.source 说明文字怎么来的：youtube-manual-caption / youtube-auto-caption / whisper。

• summaryHint 是给模型看的下一步指令，不是结果。总结由调用方模型 读 savedTo 文件后自己写——本工具不做总结。

• description 是视频简介。它有时比正文更能说明"这视频到底在讲什么"。

• 走 Whisper 时还会多一个 transcript.audio，说明音频的去向： { kept: true, keptPath }（本次保留）或 { reused: true, path }（复用了旧的）。

使用方式

你不需要记工具名，把链接丢进对话就行，模型会自己调用：

转录一下 https://www.youtube.com/watch?v=xxxxxxxx

常见任务怎么问

后三种会自然形成「工具落盘 → 模型读文件 → 加工」的流程，这也是它设计成这样 （只返回路径 + 预览）的原因。

效率上的四个事实

• 同一个视频问第二次 = 秒回（fromCache: true），不重新下载、不重新转录

• 有现成字幕的视频约 7 秒；没字幕要走 Whisper。默认模型 （large-v3-turbo）下，5 分钟视频约 3 分钟、20 分钟视频约 14 分钟； 传 model: "small" 可以快到 1/2（但质量差，见「转录质量与速度」）

• 改 YTS_MODEL、YTS_HOTWORDS 或传 model/hotwords 会让缓存自动失效 （同一视频用不同设置，结果本就该不同）。缓存的指纹包含模型、词表、语种、 compute_type、vad、补录阈值——之前只比模型，结果"改了 hotwords 却拿到旧稿"， 这个坑真的踩过。失效后如果开着 YTS_KEEP_AUDIO，会复用留下的音频、只花转录时间

• 想强制重跑就加 force，或直接说"忽略缓存"

和 Obsidian 的关系

落盘的就是标准 Markdown：frontmatter（标题/来源/频道/时长/语种/来源类型）

• 带时间戳的转录章节。把 YTS_OUTPUT_DIR 指向 vault 目录， 出来的文件可以直接当笔记读、被检索、被双链引用。

转录质量与速度

先给结论：默认用 large-v3-turbo。 要快速草稿就在调用时传 model: "small"， 或用 YTS_MODEL 改默认。

实测数据（22 分钟中文访谈，Intel i7-8850H 12 核、无 GPU、int8）。 RTF = 处理耗时 ÷ 音频时长，越小越快：

同一段音频的差距实例：

坑一：Whisper 会静默丢掉整个 30 秒窗口

faster-whisper 按 30 秒窗口推进。某一窗如果输出空文本，transcribe.py 会直接 continue 掉它（if segment["start"] == segment["end"] or not text.strip()）， 时间轴上就出现一个洞——不报错、不警告。

实测那份 22 分钟视频里，3:33–3:56 一整段（讲托福/GRE 真题和进黑名单的那段） 就这么没了；而把同一段音频单独切出来，用同样的 small 和默认参数就能正常转。 所以这不是"模型听不见"，是窗口推进的机制问题。

哪些地方容易丢：翻回原片对过，丢失的两段（3:33 和 7:02）都是插入了另一段 视频的片段、声音换了一个人的位置。声源一变，模型判定"这里不是说话"的概率就上去， 整窗被丢。这也解释了为什么补录能救回来——同一段音频换个窗口起点重新解码就正常了。

本项目的对策是缺口补录：主转录跑完后扫描时间轴缺口，把缺口重新切出来单独 转一遍，再按时间合并。这个兜底与模型无关（small 和 large-v3 都出现过整窗 丢失），控制它的是 YTS_GAP_MIN_SECONDS（默认 10 秒，设 0 关闭）。

补录有个反直觉的地方：切多长决定成败。同一个 23 秒缺口（同一台机器、同一个 small），只改"缺口前留几秒"：

所以代码里按 5→6→8 秒的顺序试几组窗口，取捞回最多的一次，够本（约六成） 就提前收工。实测那次补录第一组就命中 135 字，多花 13 秒。

补录还有一个必须防的坑：有时候正文其实没丢，只是主转录把时间戳推后了。 TEDx 那支视频开场白被记在 19.3 秒、0–19 秒显示为空，补录把同一句话又转了一遍， 贴上去就成了"同一句话说两遍"。所以补录结果会跟缺口后面的已有段落比一次覆盖率， 像"同一句话"就丢掉（日志里记 discarded_as_duplicate）。

成本上限：片头/片尾的缺口通常是音乐或掌声，捞不出东西却会跑满所有尝试 （"够本"阈值对静音永远达不到）。实测一个 19 秒的片头缺口跑满 5 组、只捞回 15 个字。所以边缘缺口只试一次、中间缺口上限 3 组；正常一次补录 只多花 3–13 秒。

已知限制：补录段和主转录在缺口边界上可能重复几个字（实测 1000 字里重复 8 字， 因为两侧对同一个词的写法不同，去重匹配不到）。补了几处、补回多少字会出现在 返回值的 gapRetry 和缓存 JSON 里，能逐条核对。

坑二：hotwords 能救专有名词——而且能自动生成，不用手工维护

同一段音频、同一个 small 模型：

所以默认会自动从标题抽词（不够再取简介）：转成简体、按标点切块、只留 2–8 字的 纯中文/拉丁块、短的优先、最多 5 个。实在这段视频的标题抽出的是 李笑来 他戒烟时 新东方名师 朗读重塑大脑 中国比特币首富——人名和惯用语都修对了。 用 YTS_AUTO_HOTWORDS=0 关掉，用 YTS_HOTWORDS 或工具参数 hotwords 叠加手动词 （补自动抽不到的名字）。

三条注意事项：

• 必须简体。繁体词基本救不回简体输出。

• 保持"词表"形态（空格分隔，别塞整句/带标点）。有过一次整句标题当 hotwords 后 解码崩坏的记录（avg_logprob −2.34、中英日韩乱码），虽然没能稳定复现，但没必要冒险。

• 它和 initial_prompt 不是一回事：后者会改变断句和标点风格，实测还漏了 21 秒，不要用。

坑三：置信度抓不到错别字，只能抓"解码崩坏"

本来想让工具直接告诉你"哪几段可疑"，实测做不到：同一个 small 跑出来的段落， avg_logprob 全都在 −0.21 / −0.23，错的和对的一样自信 （李孝萊、凶汗、名诗、必权人 全在正常区间里）。

它唯一有用的是抓崩坏：那次中英日韩乱码的崩坏，avg_logprob 掉到 −2.34，一眼可辨。 所以返回值里只在真的出现异常段时才带 lowConfidence（阈值 −1.0）， 平时不要指望它替你找错别字。

结论：想少错就换更大的模型（默认已是 large-v3-turbo），词表靠自动抽 + 偶尔手工补。

试过但没用的旋钮

省得你再折腾一遍。在本次样本上，以下改动都没有可测量的改善：

• 开关 VAD（--no-vad）、调 min_silence_duration_ms

• 强制 YTS_LANGUAGE=zh（与 auto 输出逐字相同）

• 放宽 log_prob_threshold / no_speech_threshold（阈值全关掉照样整窗丢失）

• beam_size 5 → 10

• compute_type int8 → int8_float32

真正有效的只有三件：换更大的模型、给对 hotwords、补录缺口。

配置

全部通过环境变量，写在 MCP 客户端的 env 块里。

本项目自己的配置项统一用 YTS_ 前缀。此外还有几个沿用业界通用名的变量 （HTTP_PROXY / HTTPS_PROXY / NO_PROXY、HF_ENDPOINT 等）， 它们不带前缀，因为换名字反而会让通用工具认不出来。

字幕

输出

相对路径按项目目录解析，不是当前工作目录——MCP 服务器启动时的 cwd 不可预测，按项目目录才稳定。想写到别处（比如 Obsidian vault 里）就给绝对路径：

"YTS_OUTPUT_DIR": "/Users/you/Documents/my-vault/youtube"

保留音频

默认转完就删音频：它只为这一次转录服务，16kHz wav 约 2MB/分钟 （22 分钟视频约 42MB），留在磁盘上不划算。

但保留有它的用处——换更大的模型重跑。这时候音频是唯一的重复成本 （重新下载往往比转录本身还慢），留着就能只花转录时间：

"YTS_KEEP_AUDIO": "1"

打开后：

• 音频从临时目录复制一份到 YTS_AUDIO_DIR（默认 <输出目录>/audio/）， 文件名是 <videoId>.wav，同一个视频重跑不会堆积多份

• 改了 YTS_MODEL 再跑同一个视频，缓存自动失效并复用这份音频，不重新下载

• 想清理就手动删 audio/ 目录，程序不主动回收

工具返回值里能看到实际动作：transcript.audio 为 { kept: true, keptPath } （本次保留）或 { reused: true, path }（复用了旧的）。

Whisper

网络

NO_PROXY 请写成 localhost,127.0.0.1,::1。带方括号的 [::1] 会让 Python 的 httpx 抛 InvalidURL: Invalid port，把模型下载打崩。

超时与路径（一般不用改）

后三个是给「不想用项目自带 venv / ffmpeg 不在默认位置」的情况准备的。 正常装了 ffmpeg 就不用管它们。

字幕挑选规则

按优先级排出一条候选链，前面的失败会继续试后面的：

书写系统不符会降权（要简中却给繁中），语种不符也降权。全部落空 → Whisper。

这条链值得维护，因为两条路径的代价差得很远。同一个 5:56 的视频实测： 现成人工字幕 6.8 秒，Whisper small 84.6 秒，而且字幕质量更好 （官方译稿、带 (笑声) 这类非语音提示）。

为什么必须是链而不是单选：YouTube 对自动翻译轨常年返回 429。 若只挑一条，要简中时会因为翻译轨失败而整个退回 Whisper； 有了链就能退到「原声语种字幕」这类能下的轨道。

YTS_PREFER_SUBTITLES 三档：

要中文输出请另读 中文字幕指南。 中文场景有四个反直觉的坑（自动翻译轨拿不到、zh-TW 不等于繁体、 写 zh-Hans 反而更慢、Whisper 输出繁简混排），以及繁简转换档位的选择依据。

落盘格式

frontmatter 里记录转录来源，取值：

language 记录实际命中的轨道语种（字幕轨如 zh-tw；Whisper 则记它识别出的 zh）。若做过繁简转换， 会额外有 converted_to_simplified: true——这样你能看出正文经过转换， 不会被 zh-tw 的标记误导。工具返回的 transcript.source 同义。 转换相关细节见 中文字幕指南。

排查

文件

依赖

• yt-dlp —— 下载字幕与音频

• faster-whisper / CTranslate2 —— 本地语音识别

• OpenCC —— 繁简转换

• Model Context Protocol —— MCP 标准

ffmpeg 需要单独安装（brew install ffmpeg / apt install ffmpeg）。

License

MIT