YouTube Transcript & Search MCP Server

🎬 为什么

每个使用代理工作的人都至少经历过一次这样的对话。

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!

字幕恰恰是代理自己无法获取的内容。连接此服务器之后，同样的消息就直接有了答案。

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 数据交给代理的三种方式：

Related MCP server: VidLens

⚡ 快速开始

1. 获取 API key。 在 transcriptout.com 注册，然后在 仪表盘 中创建 key。新账户可获得 100 个免费积分，且无需绑定卡。key 均以 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

代理会自行选用 get_transcript，读取带时间戳的字幕并直接据此回复。每一次响应都会附带 X-Credits-Remaining 请求头，使整个会话剩余积分一目了然。

🧰 14 个工具

全部 14 个工具在连接后自动开放。大多数调用花费 1 积分。 当调用在未到达 YouTube 之前失败时（校验错误、请求频率限制、服务端自身容量问题），积分会自动返还，所以你是为答案、而非失败而付费。一个明确的“这个视频没有字幕”也是一个答案，同样按此计费。

1. get_transcript · 1 积分

获取任意 YouTube 视频的字幕。format=text（默认）返回纯文本可读内容，最便于模型推理处理；format=json 返回带时间戳段落的 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 将以完整的字幕文件正文返回，代理可直接将其写入磁盘。srv3 为原始源 XML，不与 segment 同时使用。

2. get_video_info · 1 积分

获取单个视频的元数据（标题、频道、时长、播放数、封面）以及可用字幕语言列表，但不下载字幕。

积分使用建议： 若你同样要获取字幕，请改用 get_transcript 并带上 video_metadata=true。一次调用、一个积分即可获得两者，否则就是两次调用、两个积分。

3. search_youtube · 1 积分/页

在 YouTube 上搜索视频或频道。可通过 next_page_token 翻页，has_more 指示是否还有下一页。

4. list_channel_videos · 1 积分/页

按新到旧列出某个频道“Videos”标签页中的视频。接受 @handle、频道名称、UC... 频道 ID 或频道链接。

ids_only=true 是以低积分方式向 submit_transcripts_job 喂数据的最佳路径。

5. search_channel_videos · 1 积分/页

基于 YouTube 自带的关联度搜索在某个频道内搜索。结果标题中不包含查询词完全正常，因为结果是按相关度、而非按子串匹配排序的。

6. latest_channel_videos · 1 积分

返回频道 RSS 中最新发布的约 ~15 个视频，这是检查频道近期动态最快、最省积分的方式。

7. list_playlist_videos · 1 积分/页

按播放列表原有顺序列出其全部视频。接受 PL... 播放列表 ID 或含 list= 的链接。

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.

一键安装：

安装后，打开服务器设置，添加 Authorization 请求头，并填入你的密钥。

手动配置（~/.cursor/mcp.json）：

{
  "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"

Claude 的自定义连接器通过 OAuth 认证远程服务器，但 TranscriptOut 目前还未提供 OAuth（只支持 API 密钥）。在桌面上，请使用 Claude Code（见上方），它支持 API 密钥请求头。OAuth 支持已在路线图上。请关注 变更日志。

或者把这个加到 VS Code 用户设置（settings.json）中：

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

1. 创建新的 Agent

2. 在 “Actions” 或 “Tools” 下，添加新的 MCP Server

3. URL：https://api.transcriptout.com/mcp

4. 认证类型：API 密钥

5. 从仪表盘粘贴你的 API 密钥

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "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"
      }
    }
  }
}

在 Zed 的 settings.json 中：

{
  "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"

在 settings.json 的 augment.advanced 下：

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

在 .kilocode/mcp.json 中：

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

在设置 → 工具 → AI Assistant → MCP 中：

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

在 ~/.gemini/settings.json 中：

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

在 ~/.qwen/settings.json 中：

{
  "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"
      }
    }
  }
}

在 mcp.json 中：

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

在设置 → AI → MCP 中：

{
  "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 中，启动时会从实时目录更新（网络允许时），因此本地列表不会过期。

🍳 食谱

每个下面的提示框都可以按原样粘贴。

批量操作详解说明。 “深度归档整个频道”只是四个工具调用，而不是脚本：

1. 使用 ids_only=true 调用 list_channel_videos：每页最多返回 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 响应头返回。

• 可购买永不过期的一次性积分包，叠加在有效订阅之上。

• 查看定价 · 管理账单

🧯 当调用失败时

• 确认您的 API 密钥以 sk_ 开头

• 检查复制时是否混入多余空格

• 确认密钥在您的 仪表盘 中处于有效状态

• 已撤销的密钥会立即失败。请重新创建密钥

• 在 仪表盘 中查看余额

• 订阅或购买积分包：transcriptout.com/billing

• 404：视频在所请求的语言/字幕轨上没有字幕。这是确定性结果，重试也无法改变。

• 410：视频已被删除。

• 451：年龄受限或会员专属内容。

• 请遵守 Retry-After 响应头。两者都会自动退款

• 批量任务请使用 submit_transcripts_job：它会在您的速率限制内自动调节步调，而不会反复被拒

每个错误响应都是 {"ok": false, "code": "...", "detail": "...", "request_id": "req_..."}。 请根据机器可读的 code 分支判断，而不要依赖人工可读的文本。联系支持时请提供 request_id。

🌐 更偏好纯 REST？

您是在构建应用而不是智能体？同一后端以 JSON REST API 形式提供，支持同样的五种字幕格式，外加原始文件下载（download=true）。

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

🔗 链接

• 🌐 Website：transcriptout.com

• 📚 Docs：transcriptout.com/docs

• 🧰 Agent 技能（同一后端，无需 MCP）：github.com/artemchuikin/youtube-skills

• 💬 联系邮箱：support@transcriptout.com

📇 MCP Registry

本服务器已发布到官方 Model Context Protocol Registry，名称如下：

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

TranscriptOut 是一项独立服务，与会者YouTube 或 Google LLC，仅凭这一点,并非其附属、支持或赞助。“YouTube”是 Google LLC 的商标。