YouTube Transcript MCP

YouTube Transcript MCP 服务

一个可自托管的 Model Context Protocol 服务，可让 MCP 客户端获取公开可用的 YouTube 字幕轨道及其时间戳。它不会转录音频。它支持 Claude Desktop 和其他本地 stdio 客户端，也支持通过公开 HTTPS MCP 端点连接 ChatGPT 和 Claude 网页版/API。

集成方式

有两种连接模式：

• **本地 Claude Desktop、Cursor、VS Code 及类似客户端：**客户端通过 MCP stdio 启动 dist/index.js。YouTube 请求由你的电脑发出。
• **ChatGPT 自定义 MCP 服务和 Claude 远程自定义连接器：**这些客户端需要一个可通过公开 https:// URL 访问的 MCP 服务。在本地运行此服务，并通过隧道暴露端口 3000。服务仍会从你的电脑获取 YouTube 内容，因此 YouTube 看到的是你的家庭 IP，而非云端部署的 IP。

HTTP 端点使用官方 MCP SDK 的 Streamable HTTP 传输方式。此外，它还保留了一个直接的 REST 端点，用于脚本和运行状况检查。

安全须知：官方托管服务

本项目可自托管。作者不提供官方的公开托管 MCP 服务。

为确保安全和隐私，请克隆此代码库并自行运行服务，或将自己的实例部署到你控制的基础设施上。

**请谨慎对待声称托管本项目的第三方网站。**它们不一定与原项目有关联，也可能运行修改过的代码，或收集发送到其服务器的信息。

官方源代码： https://github.com/windows10fan648/youtube-transcript-mcp

对于非官方第三方部署的安全性、隐私或行为，作者概不负责。

快速开始

git clone https://github.com/windows10fan648/youtube-transcript-mcp.git
cd youtube-transcript-mcp
npm install
npm run build
npm test

发布到 MCP Registry

此代码库包含一个用于官方 MCP Registry 的 server.json 清单。它描述的是本地 stdio 软件包；本项目不提供官方托管的远程端点。

首次发布到 Registry 前：

1. 确认作用域 npm 软件包 @fakasys/youtube-transcript-mcp 可用，且你有权限发布。package.json 中的软件包名称必须与 server.json 中的 packages[0].identifier 一致。
2. 使用 npm 进行身份验证，然后构建并检查软件包：

   npm install
   npm run build
   npm pack --dry-run
   npm publish --access public
   

3. 从 MCP Registry releases 安装官方 mcp-publisher CLI。
4. 验证清单，使用 GitHub 进行身份验证，然后发布：

   mcp-publisher validate
   mcp-publisher login github
   mcp-publisher publish
   

package.json 中的 mcpName 值必须与 server.json 中的 name 一致。每次发布时，确保 package.json 和 server.json 中的软件包版本同步。先发布 npm 软件包，再发布其 Registry 元数据。

通过 stdio 使用 Claude Desktop

将以下内容添加到 Claude Desktop 的配置文件中：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "node",
      "args": ["C:/path/to/youtube-transcript-mcp/dist/index.js"]
    }
  }
}

使用绝对路径，然后重启 Claude Desktop，再让 Claude 转录 YouTube URL。此模式仅限本地使用，不会让 Claude 网页版能够访问此服务。

通过 HTTPS 使用 ChatGPT 和 Claude 网页版/API

启动 MCP HTTP 服务：

npm run serve

在另一个终端中，创建一个公共 HTTPS 隧道。具体来说，请使用 Tailscale Funnel

tailscale funnel --bg 3000

使用生成的 URL，并加上 /mcp，例如：

https://<YOUR_DOMAIN.ts.net/mcp

安全警告：在公开 HTTP 端点之前，请设置 MCP_AUTH_TOKEN。设置后，除 CORS 预检外的每个 HTTP 端点都需要 Authorization: Bearer <token>。任何获取到未受保护隧道 URL 的人，都可能访问其工具并消耗服务器资源。

服务仅从服务端的 YOUTUBE_COOKIE 环境变量读取可选的 YouTube 会话 Cookie（也会回退读取旧版 COOKIE/YT_COOKIE 环境变量）。调用方无法通过查询参数、请求正文或标头提供或覆盖 Cookie。切勿提交或公开这些 Cookie。

ChatGPT

在 ChatGPT 中，打开自定义连接器/MCP 服务区域，添加 HTTPS /mcp URL，并启用只读工具。具体界面可能会因 ChatGPT 的版本或工作区而异，可能将此操作标为添加自定义 MCP 服务或创建插件。然后询问：List the available transcript languages for https://www.youtube.com/watch?v=... and summarize it in Spanish. ChatGPT 可以先调用语言列表工具，选择准确的代码，然后获取该字幕。

服务不会运行大模型，也不需要 API 密钥。摘要工具会获取字幕，并附上摘要指令返回给 ChatGPT；ChatGPT 本身会读取工具结果，并使用当前对话所用的模型撰写摘要。

对于 OpenAI API，请配置一个使用相同 URL 的远程 MCP 工具。服务支持 Streamable HTTP，并以 MCP 文本内容的形式返回字幕。

Claude 网页版、Claude Desktop 远程连接器和 Claude API

在 Claude 中，打开 Customize → Connectors → Add custom connector，并输入公共 /mcp URL。如果未设置 MCP_AUTH_TOKEN，请选择 No sign in；如果启用了身份验证，请将连接器配置为发送 bearer token。Claude 的远程连接器从 Anthropic 的基础设施发起连接，因此隧道必须保持运行并可从公共网络访问。

对于 Claude API，请使用 MCP 连接器并填写公共 HTTPS URL，然后启用 list_youtube_transcript_languages、get_youtube_transcript 和 summarize_youtube_transcript 工具。无法通过 Claude API 或 Claude 网页版的远程连接器直接连接本地 stdio 服务。

直接 REST API

同一服务还提供可选的 REST 请求：

MCP_AUTH_TOKEN='replace-with-a-long-random-token' npm run serve

curl -H 'Authorization: Bearer replace-with-a-long-random-token' \
  'http://localhost:3000/mcp?videoIdOrUrl=dQw4w9WgXcQ'

curl -X POST http://localhost:3000/mcp \
  -H 'Authorization: Bearer replace-with-a-long-random-token' \
  -H 'Content-Type: application/json' \
  -d '{"videoIdOrUrl":"dQw4w9WgXcQ","format":"text"}'

工具参考

get_youtube_transcript

• videoIdOrUrl — 必填的 YouTube URL 或 11 个字符的视频 ID。支持观看页面 URL、youtu.be、Shorts、嵌入页面、直播 URL 和移动端 URL。
• lang — 可选的 ISO 639-1/BCP-47 语言代码，包括区域和文字代码，例如 en、pt-BR、es-419 或 zh-Hans。服务会选择准确匹配的字幕轨道；如果该轨道不可用，则返回错误，绝不会静默改用其他语言。

此工具返回带时间戳的纯文本，例如：

[1s] [♪♪♪]
[18s] We're no strangers to love
[22s] You know the rules and so do I

summarize_youtube_transcript

• videoIdOrUrl — 必填的 YouTube URL 或 11 个字符的视频 ID。
• lang — 可选的字幕语言代码，包括区域或文字代码，例如 pt-BR 或 zh-Hans。此参数仍用于获取字幕；摘要由已连接的 AI 执行。
• style — 可选的指令，可指定 brief、detailed 或 bullets，供已连接的 AI 客户端使用。

这是一个由客户端协助执行的工具。它会获取字幕，但不会转录音频，也不会自行调用 OpenAI、llama.cpp、Ollama 或任何其他模型。

list_youtube_transcript_languages

• videoIdOrUrl — 必填的 YouTube URL 或 11 个字符的视频 ID。

返回 YouTube 提供的字幕轨道，例如 { "code": "zh-Hans", "name": "Chinese (Simplified)", "kind": "standard", "isAutoGenerated": false }。将返回的确切 code 作为 lang 传递给 get_youtube_transcript 或 summarize_youtube_transcript。如果请求的语言代码不可用，服务会返回错误并列出可用的语言代码。请求特定字幕轨道前，请使用此工具检查可用语言。

YouTube 访问权限与限制

此项目读取公开可用的字幕轨道，包括 YouTube 提供的自动生成字幕。它不会转录音频，也不会绕过私人视频、已停用的字幕、年龄限制或 YouTube 身份验证。YouTube 官方 Data API 对字幕轨道操作要求授权；此服务改用 YouTube 的播放器字幕数据和非官方的 Node 转录库。

如果 YouTube 对云托管的部署发起质询，建议使用本地 stdio 或本地隧道。如果必须在云环境中运行，请仅在服务环境中设置 YOUTUBE_COOKIE；URL、请求正文或由调用方控制的标头中的 Cookie 会被有意忽略。

HTTP 请求的 JSON 正文大小上限为 1 MB，并设有服务端请求和标头超时。PORT 必须是 1 到 65535 之间的整数。

测试

npm run build
npm test
npm run serve

许可证

ISC