YouTube Transcript & Search MCP Server

YouTube 字幕与搜索 MCP 服务

让你的 AI Agent 读取 YouTube 内容。
提供五种格式的字幕、原生视频和频道搜索、频道和播放列表清单， 以及可在后台运行、每次最多交付 4,000 份字幕的任务。一个托管端点提供 14 种工具。无需在你的机器上运行任何程序。

为什么 · 快速开始 · 工具 · 安装 · 用法示例 · 定价 · 错误

🎬 为什么

每个使用 Agent 的人，至少都经历过一次这样的对话。

You:   Summarize this. https://www.youtube.com/watch?v=kCc8FmEb1nY
Agent: I'm not able to watch videos. If you paste the transcript here, I'll gladly help!

字幕正是 Agent 无法自行获取的内容。连接此服务后，同样的消息就能得到解决。

You:   Summarize this. https://www.youtube.com/watch?v=kCc8FmEb1nY
Agent: → get_transcript(video="kCc8FmEb1nY", video_metadata=true)      1 credit

       That's "Let's build GPT: from scratch, in code, spelled out" by Andrej
       Karpathy, 1:56:20. He starts from an empty file and a bigram model,
       derives self-attention step by step, and ends with a working GPT that...

读取一段视频很少就是任务的终点。以下比较了将 YouTube 数据提供给 Agent 的三种方式。

⚡ 快速开始

1. 获取 API 密钥。 在 transcriptout.com 注册，并在 控制面板 中创建密钥。新账户可获得 100 个免费额度， 无需绑定银行卡。密钥以 sk_ 开头，且只会显示一次。

2. 将客户端指向服务。 它使用可流式传输的 HTTP，并通过一个 Bearer 标头进行身份验证。

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

本页顶部提供了适用于 Cursor 和 VS Code 的一键按钮。其他客户端的具体代码片段请参阅 在客户端中安装。

3. 粘贴链接。

Summarize this talk and pull the three strongest quotes.
https://www.youtube.com/watch?v=dQw4w9WgXcQ

Agent 会自行选择 get_transcript，读取带时间戳的文本并据此作答。每个 响应都会携带 X-Credits-Remaining 标头，因此整个会话期间都能查看剩余额度。

🧰 14 个工具

连接后，系统会自动提供全部 14 个工具。大多数调用消耗 1 个额度。 如果调用在访问 YouTube 之前失败（例如验证错误、速率限制或我们自身的容量问题），额度会自动退还，因此你只需为答案付费，而不必为失败付费。明确返回“此视频没有字幕”也算作答案，并按一次调用计费。

1. get_transcript · 1 个额度

获取任意 YouTube 视频的文字稿。format=text（默认值）会返回易读的纯文本，便于模型推理且成本最低；format=json 会返回带时间戳的片段。

省略 segment 时，系统会将自动生成的字幕切分为约 180 个字符的片段，并完全按照人工字幕作者的分段方式返回。无论返回的是哪种字幕，都需要统一片段大小时，请设置此参数。

示例输出（format=json）：

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "kind": "manual",
  "transcript": [
    { "text": "Never gonna give you up", "start": 18.0, "duration": 4.12 },
    { "text": "Never gonna let you down", "start": 22.12, "duration": 3.85 }
  ]
}

srt 和 vtt 会以完整的字幕文件正文形式返回，可直接由 Agent 写入磁盘。srv3 是原始源 XML，不能与 segment 一起使用。

2. get_video_info · 1 个额度

获取单个视频的元数据（标题、频道、时长、观看次数、缩略图），以及可用文字稿语言列表，无需下载字幕。

额度使用建议： 如果你还要获取文字稿，请改用 video_metadata=true 调用 get_transcript。这样一次调用只需 1 个额度即可同时返回两者，而分开调用则需要两次额度。

3. search_youtube · 每页 1 个积分

搜索 YouTube 视频或频道。使用 next_page_token 翻页。has_more 用于指示是否还有下一页。

4. list_channel_videos · 每页 1 个积分

按发布时间从新到旧列出频道「视频」标签页中的视频。接受 @handle、频道名称、UC... 频道 ID 或频道 URL。

ids_only=true 是将视频传入 submit_transcripts_job 的低成本方式。

5. search_channel_videos · 每页 1 个积分

使用 YouTube 原生相关性搜索在单个频道内搜索。结果标题中不包含查询词是正常情况。结果按相关性排序，而非按子字符串匹配排序。

6. latest_channel_videos · 1 个积分

通过频道的 RSS Feed 获取其最新的约 15 个视频。这是查看频道近期发布内容最快、成本最低的方式。

7. list_playlist_videos · 每页 1 个积分

按播放列表顺序列出播放列表中的所有视频。接受 PL... 播放列表 ID 或包含 list= 的 URL。

8. search_playlist_videos · 1 个积分

通过标题中的子字符串（不区分大小写）查找播放列表中的视频。YouTube 不支持原生播放列表搜索，因此此工具会扫描最多 500 个播放列表条目。truncated=true 表示扫描范围之外可能还有更多匹配项。

9. submit_transcripts_job · 每个视频 1 个积分

一次为大量视频（最多 4,000 个）排队获取字幕，并立即返回 job_id。任务会在后台继续处理，速度取决于你的速率限制。需要处理的视频超过少数几个时，请使用此工具，而不要循环调用 get_transcript。

需要用户密钥（sk_...）。提交时会扣除积分；如果因我们的原因无法交付某个视频，则会退还该视频对应的积分。

10. get_transcripts_job · 免费

查看批处理任务的进度：状态（queued/running/done/cancelled），以及已就绪、失败和待处理的视频数量。查询已付费的任务不收费。

11. get_transcripts_results · 免费

获取批处理任务中已完成的字幕，按提交顺序排列，并使用 next_page_token 分页（limit 为 1-500，默认为 100）。结果会在获取后立即显示，因此你可以在任务完成前读取。每个条目都与该视频的 get_transcript 返回结果完全相同，另附其状态。

12. get_transcripts_result · 免费

按视频 ID 获取批处理任务中单个视频的结果，无需翻阅整个结果集。404 表示任务不存在或该视频尚未完成，因此在下结论前请先检查 get_transcripts_job。

13. cancel_transcripts_job · 免费

取消批处理任务。仅会退还尚未开始处理的视频所对应的积分。已获取的视频仍会保留在结果中，且仍需付费。

14. get_credits · 免费

查看密钥的剩余积分余额，无需参数。每个响应的 X-Credits-Remaining 标头中也会返回余额，但模型无法读取标头，因此用户实际询问余额时需要使用此工具。在大型批处理前查看也很方便，因为提交时每个视频会扣除 1 个积分。

🔌 在客户端中安装

该服务是远程服务，因此以下所有安装方式都只是配置项，仅此而已。它们都需要相同的两个值：来自快速开始的 URL 和 Bearer 标头。

建议只设置一次，并作为客户端的常驻规则

将以下内容添加到客户端的规则／说明中后，只需粘贴 YouTube 链接，无需再输入 “transcript”一词：

Whenever a YouTube link or video ID appears in my message, call the
transcriptout get_transcript tool first and answer from the transcript,
whether I asked for a summary, a quote, a translation or a question.

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

claude mcp add --transport http transcriptout https://api.transcriptout.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

"mcp.servers": {
  "transcriptout": {
    "type": "http",
    "url": "https://api.transcriptout.com/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "serverUrl": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "type": "streamableHttp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "context_servers": {
    "transcriptout": {
      "source": "remote",
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "type": "streamable-http",
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

amp mcp add transcriptout https://api.transcriptout.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

"augment.advanced": {
  "mcpServers": [
    {
      "name": "transcriptout",
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  ]
}

{
  "mcpServers": {
    "transcriptout": {
      "type": "streamable-http",
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "httpUrl": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "httpUrl": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "serverUrl": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "transcriptout": {
    "url": "https://api.transcriptout.com/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
}

{
  "url": "https://api.transcriptout.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}

🧩 安装为 Agent 插件

此仓库根目录是符合规范的 Agent Plugins 1.0.0 软件包，是 ChatGPT、Codex、Cursor、GitHub Copilot、Kiro 和 VS Code 支持的可移植格式。一次安装即可获得 MCP 服务，以及随附的 youtube 技能，用于教会 Agent 何时使用各项工具，以及如何避免浪费额度。

plugin.json                # manifest
mcp.json                   # hosted MCP server, streamable-http
skills/youtube/SKILL.md    # when + how to use the 14 tools

VS Code。 打开命令面板 → Chat: Install Plugin From Source，然后粘贴：

https://github.com/artemchuikin/youtube-mcp

或者在 settings.json 中注册本地克隆：

"chat.pluginLocations": { "/absolute/path/to/youtube-mcp": true }

Cursor。 点击侧边栏中的 Customize → 找到该插件 → Install。本地克隆的安装方式：

git clone https://github.com/artemchuikin/youtube-mcp ~/.cursor/plugins/local/transcriptout

然后执行 Developer: Reload Window。

ChatGPT、Codex、GitHub Copilot、Kiro 及其他客户端。 将客户端的插件机制指向此仓库或本地克隆。Agent Plugins 1.0.0 标准化的是软件包格式，而非安装方式，因此每个客户端都有自己的安装流程。

此软件包不包含任何凭据，Agent Plugins 1.0.0 禁止嵌入密钥。服务通过你在客户端 MCP 设置中添加的 API 密钥进行身份验证（参见密钥与安全）。你也可以自行验证软件包：

curl -sO https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
curl -sO https://agent-plugins.org/schemas/1.0.0/mcp.schema.json
npx ajv-cli@5 validate --spec=draft2020 -s plugin.schema.json -d plugin.json
npx ajv-cli@5 validate --spec=draft2020 -s mcp.schema.json    -d mcp.json

🔑 密钥与安全

• 密钥仅在创建时显示一次。请将其保存在环境变量中，并避免将其纳入版本控制。
• 如果密钥泄露，在你于控制面板中撤销后便会立即失效。一个账户最多可持有 20 个密钥，因此请为每台机器单独创建一个。
• 想直接在聊天中操作？安装了配套 youtube-skills 的 Agent 可以通过电子邮件和 6 位验证码打开账户并为你创建密钥，无需使用浏览器。
• 目前尚无 OAuth 流程，因此无法发送自定义标头的客户端连接器（Claude Desktop 和 Claude Web）暂时应通过 Claude Code 使用。

🐳 在本地运行

托管端点无需安装，但仅支持 stdio 的客户端、沙盒和容器平台有时需要独立运行一个进程。此仓库自带一个：server.js 是完整的本地 MCP 服务（官方 SDK、stdio 传输），其 14 个工具各自会向 TranscriptOut REST API 发起一次 HTTPS 调用——这与任何由 SaaS 后端支持的 MCP 服务采用的模式相同。

# as a container
docker build -t transcriptout-mcp https://github.com/artemchuikin/youtube-mcp.git
docker run -i -e TRANSCRIPTOUT_API_KEY=sk_your_key transcriptout-mcp

# or straight from a checkout (Node 20+)
npm install && TRANSCRIPTOUT_API_KEY=sk_your_key node server.js

即使没有密钥，它仍会连接并列出所有工具；调用工具时会返回清晰的 401 错误，说明如何获取密钥。工具定义随附于 tools.json，并会在启动时于网络可用的情况下从实时目录刷新，因此本地工具列表始终保持最新。

🍳 食谱

以下每条提示词都可以直接复制粘贴使用。

批量操作示例。“归档整个频道”只需调用 4 次工具，无需编写脚本：

1. 使用 list_channel_videos 并设置 ids_only=true：每页最多可获取 500 个视频 ID
2. 使用这些 ID 调用 submit_transcripts_job（最多 4,000 个，计费前会删除重复项，使用 idempotency_key 重试无需付费）
3. 调用 get_transcripts_job，直到 status 为 done。任务会在你的速率限制范围内自行控制处理节奏
4. 逐页调用 get_transcripts_results，即使任务仍在运行，也可以读取结果

服务未能提供的内容会按视频退款，因此账单金额与实际归档内容相符。

💳 价格和限制

• 订阅额度可通过滑块从每月 1,000 调至 100,000，每次递增 1,000；额度越大，每 1,000 的单价越低（每月 10,000 额度的价格为 $27.49，而非 $44.90）。年付折扣随额度增加而提高，从约 16% 增至约 35%。
• 1 个额度 = 1 次成功响应的请求。 在请求到达 YouTube 之前失败的调用（验证失败、触发速率限制、我们的服务容量不足）会自动退款。当前余额会显示在 X-Credits-Remaining 标头中。
• 可在有效订阅之外购买一次性额度包，额度永不过期。
• 查看价格 · 管理账单

🧯 调用失败时

🌐 更喜欢使用纯 REST？

正在构建应用而不是 Agent？同一后端也提供 JSON REST API，支持相同的五种字幕格式，以及原始文件下载（download=true）。

基础 URL：https://api.transcriptout.com/v1

客户端库为 Python 和 Node.js 提供封装。它们都可直接替代流行的开源库，切换时只需修改一行导入语句。

pip install transcriptout   # replaces youtube-transcript-api
npm i transcriptout         # replaces youtube-transcript

来源：youtube-transcript-python · youtube-transcript-js

🔗 链接

• 🌐 网站： transcriptout.com
• 📚 文档： transcriptout.com/docs
• 🧰 Agent 技能（使用相同后端，无需 MCP）： github.com/artemchuikin/youtube-skills
• 🐍 Python 库： github.com/artemchuikin/youtube-transcript-python
• 📦 Node.js 库： github.com/artemchuikin/youtube-transcript-js
• 💬 联系方式： [email protected]

📇 MCP Registry

此服务已发布到官方 Model Context Protocol Registry，名称为：

com.transcriptout/youtube-transcript-and-youtube-search

TranscriptOut 是一项独立服务，与 YouTube 或 Google LLC 没有关联，也未获其认可或赞助。“YouTube”是 Google LLC 的商标。

_{© 2026 TranscriptOut · 基于 MIT License 发布}