YouTube Transcripts

YouTube Transcript Agent

将任意 YouTube 视频、播放列表或频道转换为适用于 Agent 的转录文本上下文。

此软件包提供：

• ytx，用于转录文本、频道任务、播放列表任务、轮询和 ZIP 下载的 CLI
• 面向编码 Agent 和桌面助手的本地 stdio MCP 服务
• 关于使用托管 /mcp 端点和 Developer API 的文档

安装

无需安装即可运行：

npx youtube-transcript-agent --help

或全局安装：

npm install -g youtube-transcript-agent
ytx --help

身份验证

CLI 按以下顺序读取身份验证信息：

1. YOUTUBE_TRANSCRIPT_API_KEY
2. 由 ytx auth set-key 创建的本地配置

设置 API 密钥：

npx youtube-transcript-agent auth set-key <api_key>

或使用环境变量：

export YOUTUBE_TRANSCRIPT_API_KEY=<api_key>

PowerShell：

$env:YOUTUBE_TRANSCRIPT_API_KEY="<api_key>"

CLI 用法

获取账户额度：

npx youtube-transcript-agent credits

获取单个转录文本：

npx youtube-transcript-agent transcript FOp280ZAxhg --timestamps

下载频道转录文本：

npx youtube-transcript-agent channel download "@mkbhd" --max 25 --wait --output channel.zip

下载播放列表转录文本：

npx youtube-transcript-agent playlist download <playlist_url_or_id> --max 25 --wait --output playlist.zip

轮询任务：

npx youtube-transcript-agent jobs status <job_id>

下载已完成的任务：

npx youtube-transcript-agent jobs download <job_id> --output transcripts.zip

本地 MCP

启动本地 stdio MCP 服务：

npx youtube-transcript-agent mcp

此命令会等待 stdin 中的 JSON-RPC 消息。Agent 客户端应使用以下命令启动它：

Command: npx
Args: youtube-transcript-agent mcp
Env:
  YOUTUBE_TRANSCRIPT_API_KEY=<api_key>

可用的 MCP 工具：

• get_transcript
• get_channel_info
• list_channel_videos
• start_channel_job
• start_playlist_job
• get_job_status
• get_download_url

手动冒烟测试：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx youtube-transcript-agent mcp

托管 MCP

如果你的 API 服务已部署并启用托管 MCP：

Endpoint: https://api.youtubetranscripts.fbetteo.com/mcp
Auth: Authorization: Bearer <api_key>

列出工具：

curl -X POST "https://api.youtubetranscripts.fbetteo.com/mcp" \
  -H "Content-Type: application/json" \
  --data-raw '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

调用工具：

curl -X POST "https://api.youtubetranscripts.fbetteo.com/mcp" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  --data-raw '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_transcript","arguments":{"video_url":"FOp280ZAxhg"}}}'

Agent 技能

此代码库包含一个可安装的技能模板，位于：

agent-skill/skill.md

如需分发，请将该文件作为根目录下的 skill.md 发布到单独的公开技能代码库中。

故障排除

高级 API 主机覆盖

大多数用户无需设置 API URL。此软件包默认使用托管的生产 API。

仅在本地开发、预发布、自托管部署或调试时设置自定义基础 URL：

export YOUTUBE_TRANSCRIPT_API_BASE_URL=http://127.0.0.1:8000

或将其保存到本地 CLI 配置中：

npx youtube-transcript-agent auth set-key <api_key> --base-url http://127.0.0.1:8000

故障排除

如果出现 fetch failed，且 API 日志中没有任何记录，说明 CLI 无法连接到 API 主机。请检查：

echo "$YOUTUBE_TRANSCRIPT_API_BASE_URL"
echo "$API_BASE_URL"
cat ~/.youtube-transcript-agent/config.json 2>/dev/null

CLI 基础 URL 的优先级如下：

1. YOUTUBE_TRANSCRIPT_API_BASE_URL
2. API_BASE_URL
3. 已保存的本地配置
4. 软件包默认值

在 Windows PowerShell 中，请为频道账号句柄加上引号：

node cli/dist/cli.js channel download "@mkbhd" --max 2 --wait

PowerShell 会将 curl 别名映射到 Invoke-WebRequest；请使用 curl.exe 或 Invoke-RestMethod。