YouTube MCP Server

基于原始 claude-code-youtube-mcp 仓库改编的 YouTube MCP 服务器。此版本同时支持 STDIO 和 Streamable HTTP 传输，因此既可以在本地为 Claude Code 运行，也可以远程部署为 Claude.ai 自定义连接器。

该服务器提供 YouTube Data API v3 工具，用于视频搜索、元数据、频道信息、播放列表、评论、热门视频、互动分析、字幕、章节、SponsorBlock 清理以及最多重播热力图。

改编自：https://github.com/wynandw87/claude-code-youtube-mcp

本地运行

npm install
npm run build
npm run start:http

端点：

GET  /health
POST /mcp

Related MCP server: YouTube MCP Server

环境变量

YOUTUBE_API_KEY=your_key_here

请勿将你的 API 密钥提交到 GitHub。请将其保存在本地环境、.env 或部署平台的环境变量中。

Railway 部署

1. 在 Railway 上部署此 GitHub 仓库。

2. 在 Railway 中添加 YOUTUBE_API_KEY 环境变量。

3. 将启动命令设置为：

npm run start:http

4. 使用公共 MCP 端点：

https://your-domain/mcp

快速开始

第 1 步：获取 API 密钥

1. 前往 Google Cloud Console

2. 创建一个项目（或选择现有项目）

3. 启用 YouTube Data API v3：

   • 前往 API Library

   • 点击 启用

4. 创建 API 密钥：

   • 前往 Credentials

   • 点击 创建凭据 > API 密钥

5. 复制该密钥（第 3 步中会用到）

第 2 步：安装前置条件

• Node.js 18+ - 在此下载

• Claude Code CLI - 安装指南

第 3 步：安装 MCP 服务器

3.1 克隆仓库

git clone https://github.com/wynandw87/claude-code-youtube-mcp.git
cd claude-code-youtube-mcp

3.2 安装依赖

macOS / Linux / Windows：

npm install

注意： 依赖安装和服务器构建会在一步内自动完成。

3.3 注册到 Claude Code

选择你的安装范围：

将 YOUR_API_KEY 替换为你的实际 YouTube Data API 密钥，并使用 dist/index.js 的完整路径。

提示： 要获取完整路径，请在克隆的目录中运行：

• macOS/Linux：echo "$(pwd)/dist/index.js"

• Windows：echo %cd%\dist\index.js

macOS / Linux：

claude mcp add -s user youtube -e YOUTUBE_API_KEY=YOUR_API_KEY -- node /full/path/to/dist/index.js

Windows（CMD）：

claude mcp add -s user youtube -e "YOUTUBE_API_KEY=YOUR_API_KEY" -- node "C:\full\path\to\dist\index.js"

Windows（PowerShell）：

claude mcp add -s user youtube -e "YOUTUBE_API_KEY=YOUR_API_KEY" '--' node "C:\full\path\to\dist\index.js"

备选方案：使用 npm 辅助工具（如果 API 密钥已在环境中设置）

export YOUTUBE_API_KEY=YOUR_API_KEY
npm run install:claude

第 4 步：重启 Claude Code

关闭并重新打开 Claude Code，使更改生效。

第 5 步：验证安装

claude mcp list

你应该会看到 youtube 显示为已连接状态。

功能特性

字幕与隐藏式字幕

• 获取字幕（get_transcript）- 获取带时间戳的完整视频字幕，支持多种语言

• 搜索字幕（search_transcript）- 查找关键词或短语在视频中出现的位置及时间戳

• 清理字幕（get_clean_transcript）- 通过 SponsorBlock 移除赞助、片头、片尾和填充内容的字幕

• 提取章节（extract_chapters）- 从视频描述中解析章节时间戳

搜索与发现

• 搜索视频（search_videos）- 完整的 YouTube 搜索，支持按日期、时长、类型和排序方式筛选

• 频道内搜索（search_within_channel）- 搜索特定创作者发布的视频

• 获取热门视频（get_trending_videos）- 按地区和类别获取当前热门视频

• 获取频道视频（get_channel_videos）- 获取频道的最新上传视频，按日期或观看次数排序

视频与频道信息

• 视频元数据（get_video_metadata）- 标题、描述、时长、观看次数、点赞数、标签等

• 频道信息（get_channel_info）- 订阅者数量、视频数量、描述、国家/地区

• 播放列表项目（get_playlist_items）- 播放列表中的所有视频，包含位置和元数据

分析与互动

• 计算互动率（calculate_engagement）- 根据公开统计数据计算点赞率、评论率和互动率

• 最多重播（get_most_replayed）- 显示观众最常重看部分的热力图数据

• 视频评论（get_video_comments）- 带点赞数和回复数的热门评论

实用工具

• 解析 YouTube URL（parse_youtube_url）- 从任何 YouTube URL 格式中提取视频/频道/播放列表 ID

使用方法

安装完成后，使用触发短语来调用 YouTube 工具：

或者直接自然提问：

• "获取这个 YouTube 视频的字幕并总结一下"

• "这个视频最多重播的部分是哪些？"

• "在这个频道上查找最近关于 TypeScript 的视频"

• "这个视频有多少观看次数和点赞数？"

• "获取这个视频的评论并总结情感倾向"

• "显示这个教程的章节"

• "获取没有赞助朗读的干净字幕"

• "YouTube 游戏类目前有什么热门内容？"

工具参考

parse_youtube_url

解析任何 YouTube URL 格式并提取标识符。无需 API 密钥。

参数：

• url（字符串，必填）- 任何 YouTube URL 或视频 ID

支持的格式： youtube.com/watch?v=、youtu.be/、/shorts/、/embed/、/playlist?list=、/channel/、/@handle、/c/、/user/、裸视频 ID

get_transcript

获取 YouTube 视频的完整字幕/隐藏式字幕。无需 API 密钥。

参数：

• url（字符串，必填）- YouTube 视频 URL 或视频 ID

• lang（字符串，可选）- 字幕语言代码（默认："en"）

search_transcript

在视频字幕中搜索关键词或短语。

参数：

• url（字符串，必填）- YouTube 视频 URL 或视频 ID

• query（字符串，必填）- 要搜索的关键词或短语

• lang（字符串，可选）- 字幕语言代码（默认："en"）

extract_chapters

从视频描述中提取章节时间戳。

参数：

• url（字符串，必填）- YouTube 视频 URL 或视频 ID

get_clean_transcript

通过 SponsorBlock 获取移除赞助朗读、片头、片尾和填充内容后的字幕。

参数：

• url（字符串，必填）- YouTube 视频 URL 或视频 ID

• lang（字符串，可选）- 字幕语言代码（默认："en"）

get_most_replayed

获取"最多重播"热力图数据，显示观众最常重看的部分。

参数：

• url（字符串，必填）- YouTube 视频 URL 或视频 ID

注意： 需要大约 5 万次以上的观看次数才能获得热力图数据。

search_videos

使用完整筛选功能搜索 YouTube。

参数：

• query（字符串，必填）- 搜索查询

• max_results（数字，可选）- 结果数量，1-50（默认：10）

• order（字符串，可选）- "relevance"、"date"、"viewCount"、"rating"（默认："relevance"）

• duration（字符串，可选）- "short"（<4 分钟）、"medium"（4-20 分钟）、"long"（>20 分钟）

• upload_date（字符串，可选）- "hour"、"day"、"week"、"month"、"year"

• type（字符串，可选）- "video"、"channel"、"playlist"（默认："video"）

get_video_metadata

获取 YouTube 视频的详细元数据。

参数：

• url（字符串，必填）- YouTube 视频 URL 或视频 ID

返回内容： 标题、描述、频道、时长、观看/点赞/评论数量、标签、类别、缩略图、直播状态等。

get_channel_info

获取 YouTube 频道信息。

参数：

• url（字符串，必填）- YouTube 频道 URL、@handle 或频道 ID

返回内容： 标题、描述、订阅者/视频/观看数量、国家/地区、自定义 URL 和缩略图。

get_playlist_items

获取 YouTube 播放列表中的所有视频。

参数：

• url（字符串，必填）- YouTube 播放列表 URL 或播放列表 ID

• max_results（数字，可选）- 项目数量，1-50（默认：25）

get_channel_videos

获取 YouTube 频道的近期视频。

参数：

• url（字符串，必填）- YouTube 频道 URL、@handle 或频道 ID

• max_results（数字，可选）- 视频数量，1-50（默认：25）

• order（字符串，可选）- "date"、"viewCount"（默认："date"）

get_trending_videos

获取当前热门/流行的 YouTube 视频。

参数：

• region_code（字符串，可选）- ISO 3166-1 alpha-2 国家/地区代码（默认："US"）

• category_id（字符串，可选）- YouTube 类别 ID（例如 "10" 表示音乐，"20" 表示游戏，"28" 表示科学与技术）

• max_results（数字，可选）- 结果数量，1-50（默认：10）

search_within_channel

在特定 YouTube 频道内搜索视频。

参数：

• url（字符串，必填）- YouTube 频道 URL、@handle 或频道 ID

• query（字符串，必填）- 搜索查询

• max_results（数字，可选）- 结果数量，1-50（默认：10）

get_video_comments

获取 YouTube 视频的顶级评论。

参数：

• url（字符串，必填）- YouTube 视频 URL 或视频 ID

• max_results（数字，可选）- 评论数量，1-100（默认：20）

• order（字符串，可选）- "relevance"、"time"（默认："relevance"）

calculate_engagement

计算 YouTube 视频的互动指标。

参数：

• url（字符串，必填）- YouTube 视频 URL 或视频 ID

返回内容： 观看次数、点赞数、评论数、点赞率、评论率和总体互动率。

工作原理

此 MCP 服务器通过 stdio 传输连接到 Claude Code，并提供 15 个工具：

注意： 5 个工具无需 API 密钥即可使用（字幕、SponsorBlock、热力图、URL 解析）。其余 10 个需要 YouTube Data API v3 密钥。

配置

环境变量

YouTube API 配额

YouTube Data API v3 每日配额为 10,000 单位。每个工具消耗的配额不同：

提示： 搜索操作最消耗配额。当你只需要最新上传的视频时，请使用 get_channel_videos（1 单位）而不是 search_within_channel（100 单位）。

故障排除

修复 API 密钥

如果你输入了错误的 API 密钥，请移除并重新安装：

claude mcp remove youtube

然后使用上面第 3.3 步中的命令重新安装（使用你最初安装时使用的相同作用域）。

MCP 服务器未显示

检查服务器是否已安装：

claude mcp list

如果未列出，请按照第 3 步进行安装。

服务器无法启动

1. 验证你的 API 密钥在 Google Cloud Console 中是否有效

2. 检查 YouTube Data API 是否已启用：

   • 前往 API Library

   • 应显示"已启用"

3. 检查 Node.js 版本（需要 18+）：

   node --version

4. 确保服务器已构建 — 如果 dist/index.js 缺失，请重新运行 npm install

连接错误

1. 检查 dist/index.js 是否存在 — 如果不存在，请运行 npm install

2. 验证路径是否为绝对路径，在 claude mcp add 命令中

3. 在配置更改后重启 Claude Code

配额超限

如果你看到"quotaExceeded"错误：

• 等到太平洋时间午夜（配额每日重置）

• 使用不同的 API 密钥

• 优先使用低成本工具（get_video_metadata 为 1 单位）而不是搜索工具（100 单位）

字幕不可用

有些视频禁用了字幕。get_transcript 工具会返回明确的错误信息。请尝试：

• 使用不同的语言代码（例如 lang: "es"）

• 即使没有手动字幕，自动生成的字幕也可能可用

超时错误

对于慢速连接，请增大 YOUTUBE_TIMEOUT 环境变量：

claude mcp add -s user youtube -e YOUTUBE_API_KEY=YOUR_KEY -e YOUTUBE_TIMEOUT=60000 -- node /path/to/dist/index.js

查看当前配置

claude mcp list

贡献

欢迎提交 Pull Request！请保持简单且对初学者友好。

许可证

MIT

为 Claude Code 社区而制作