YouTube MCP 服务器

一个开源的模型上下文协议（MCP）服务器，用于从 MCP 客户端（如 Claude Desktop、Claude Code 和 Codex）使用 YouTube。

主要工作流程是：

1. 向 MCP 客户端提供一份歌曲列表。

2. 在做出任何更改之前，先查看按排名排序的 YouTube 匹配结果。

3. 从选定的视频创建私有播放列表。

该服务器还将提供注重配额的工具，用于搜索 YouTube 以及读取视频、频道、播放列表和评论。

[!IMPORTANT] TypeScript 包、stdio 服务器、公开和已认证读取、PKCE OAuth、音乐准备、确认的新播放列表创建以及完整的预览播放列表变更均已实现并通过测试。准备好的音乐草稿可以提交到新播放列表，或追加到已有的自有播放列表中。

设计目标

• 安全的播放列表写入，采用提交前预览语义。

• 仅使用官方 YouTube Data API v3 端点。

• 自带 Google OAuth 客户端；本项目绝不附带共享的 Google 凭据。

• 尽可能将密钥存储在操作系统钥匙串中。

• 可预测的配额使用、分页、缓存、重试和规范化错误。

• 本地 stdio 传输，安装简单且攻击面小。

• 结构化、有界工具输出，将 YouTube 内容视为不可信数据。

• 在 Node.js 20.17 或更高版本上提供跨平台 TypeScript 支持。

Related MCP server: youtube-music-mcp

计划中的 v1 范围

读取工具

• 搜索视频、频道和播放列表。

• 读取视频、频道、播放列表和评论数据。

• 读取已认证用户的频道、上传内容和播放列表。

• 返回提供方分页令牌，用于显式、无状态的分页。

音乐播放列表工作流

• 每次准备请求最多接受 50 条结构化曲目。

• 搜索并排名可能的 YouTube 音乐视频匹配结果。

• 显示歧义和备选方案，而不是静默选择弱匹配。

• 将明确选定的匹配提交到新播放列表或已有的自有播放列表。

• 默认将新播放列表设为 private。

评论管理

• 在视频上发布顶级评论，或回复已有评论。

• 在预览和一次性句柄之后，删除评论或设置其审核状态。

• 使用播放列表写入已请求的 youtube.force-ssl 范围，因此无需额外同意。

播放列表管理

• 创建播放列表并添加视频。

• 更新播放列表元数据或隐私设置。

• 重新排序或移除播放列表项目。

• 在发出短期、一次性确认句柄后删除播放列表。

播放列表更新、项目移除/重新排序和删除使用两个工具：youtube_prepare_playlist_mutation 返回精确差异和 10 分钟句柄而不进行写入；youtube_apply_playlist_mutation 在消耗该句柄一次之前重新检查所有权和播放列表快照。

视频上传和生命周期

• 通过可恢复上传上传本地视频文件，默认设为 private。

• 更新您拥有的视频的标题、描述、标签或隐私设置。未指定的字段会保留而不是清除。

• 从本地 JPEG 或 PNG 设置自定义缩略图。

• 预览然后永久删除您拥有的视频。

视频写入需要额外的 youtube.upload 范围，如果配置文件在未授权该范围的情况下被授权，则直接拒绝。youtube_plan_video_upload 验证文件并报告成本，而无需联系 YouTube，因为 videos.insert 花费 1600 单位——每次上传约占默认每日预算的 16%。上传从不重试：如果结果未知，会报告该情况，以便您检查是否部分上传，而不是发布重复内容。

播放列表、评论和视频管理是已实现的写入面。分析报告（0.8）在路线图上，尚不可调用。评分、订阅和频道设置写入仍然永久超出范围。

设置

npm 包尚未发布，因此服务器从克隆的仓库构建和运行。请按顺序完成这些步骤。

第 1 步 — 检查 Node.js 和 npm

node -v
npm -v

如果 node -v 打印 v20.17 或更高版本，且 npm -v 打印版本号，请跳到第 3 步。如果任一命令报告"command not found"，请继续第 2 步。

第 2 步 — 安装 Node.js 和 npm（仅当第 1 步失败时）

npm 随 Node.js 一起提供；安装 Node 会同时安装两者。为您的平台选择一行，然后重新运行第 1 步确认。

如果您不想在系统范围内安装 Node，或者需要并排安装多个 Node 版本，请使用版本管理器：

# macOS and Linux
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22

在 Windows 上，等效工具是 nvm-windows：nvm install 22 然后 nvm use 22。

安装后关闭并重新打开终端，然后重新运行 node -v 和 npm -v。

第 3 步 — 安装依赖并构建

git clone <repository-url>
cd "Youtube MCP"
npm ci
npm run build

npm ci 安装 package-lock.json 中的确切版本；仅当您打算更改依赖时才使用 npm install。构建将可执行文件写入 dist/cli/index.js，以下每个命令都会调用它。

验证构建和本地数据目录：

node dist/cli/index.js doctor

第 4 步 — 创建 Google 凭据

以下所有内容都来自您自己的 Google Cloud 项目。本项目绝不附带共享的 Google 凭据。

1. 在 Google Cloud 控制台中创建或选择一个项目。

2. 为该项目启用 YouTube Data API v3。

3. 创建 API 密钥（凭据 → 创建凭据 → API 密钥）。这用于公开读取。

4. 配置 OAuth 同意屏幕。当项目处于"测试"状态时，在测试用户下添加您自己的 Google 帐户，否则 login 将被拒绝。

5. 创建类型为桌面应用的 OAuth 客户端，然后复制其客户端 ID 和客户端密钥。

Google 即使在已安装应用中也需要授权码交换中的 client_secret，因此 PKCE 在这里是对密钥的补充，而不是替代。

第 5 步 — 服务器需要的凭据

总共有四个凭据。您提供前三个；第四个由 login 为您获取。

可选环境变量：YOUTUBE_MCP_PROFILE（默认 default）、YOUTUBE_MCP_DATA_DIR 和 YOUTUBE_MCP_LOG_LEVEL（error、warn、info、debug）。参见 .env.example。

切勿将其中任何内容粘贴到聊天消息、共享的 MCP 配置文件或将被提交的命令中。优先使用交互式提示或客户端的环境/密钥注入字段。

第 6 步 — 运行 setup，然后登录

按顺序运行。setup 会重写配置文件存储的范围和频道身份，因此在 login 之后运行它会丢弃该状态并要求重新登录。

macOS 和 Linux：

YOUTUBE_OAUTH_CLIENT_ID="YOUR_DESKTOP_CLIENT_ID" \
  YOUTUBE_OAUTH_CLIENT_SECRET="YOUR_DESKTOP_CLIENT_SECRET" \
  node dist/cli/index.js setup
node dist/cli/index.js login
node dist/cli/index.js status

Windows PowerShell：

$env:YOUTUBE_OAUTH_CLIENT_ID  = "YOUR_DESKTOP_CLIENT_ID"
$env:YOUTUBE_OAUTH_CLIENT_SECRET = "YOUR_DESKTOP_CLIENT_SECRET"
node dist\cli\index.js setup
node dist\cli\index.js login
node dist\cli\index.js status
Remove-Item Env:\YOUTUBE_OAUTH_CLIENT_SECRET

为避免将密钥放入 shell 历史记录或进程表中，请省略两个变量，让 setup 提示输入：

node dist/cli/index.js setup

当终端是交互式时，setup 会提示输入每个缺失的值。

login 打开 Google 的授权页面，并通过 127.0.0.1 上的随机回环端口返回，使用 PKCE S256 和随机状态值。当配置文件未存储客户端密钥时，它会在打开浏览器之前立即失败。

要撤销并移除存储的凭据：

node dist/cli/index.js logout

第 7 步 — 启动服务器

YOUTUBE_API_KEY="your-api-key" node dist/cli/index.js serve

服务器通过 stdio 使用 MCP 协议通信，因此通常由客户端启动而不是手动启动。可用命令为 serve、doctor、status、setup、login 和 logout。

本地数据位置

配置文件、配额账本、草稿和操作日志存放在 0700 目录中：

使用 YOUTUBE_MCP_DATA_DIR 覆盖。要移除所有本地状态，请运行 logout 然后删除该目录。钥匙串条目由 logout 移除。

将客户端连接到本地构建

在包发布之前，将客户端指向您构建的 dist/cli/index.js 的绝对路径。

Claude Code

claude mcp add youtube --scope user \
  --env YOUTUBE_MCP_PROFILE=default \
  --env YOUTUBE_API_KEY=your-api-key -- \
  node /absolute/path/to/Youtube\ MCP/dist/cli/index.js serve

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/absolute/path/to/Youtube MCP/dist/cli/index.js", "serve"],
      "env": {
        "YOUTUBE_MCP_PROFILE": "default",
        "YOUTUBE_API_KEY": "your-api-key"
      }
    }
  }
}

Codex

[mcp_servers.youtube]
command = "node"
args = ["/absolute/path/to/Youtube MCP/dist/cli/index.js", "serve"]

[mcp_servers.youtube.env]
YOUTUBE_MCP_PROFILE = "default"
YOUTUBE_API_KEY = "your-api-key"

拉取更改后重新运行 npm run build；客户端执行编译后的 dist 输出，而不是 src。

此本地服务器的 Google 授权由其自己的 setup 和 login 命令执行。客户端级别的 MCP 登录命令不会替代下游的 Google OAuth 流程。

发布后的客户端配置

包发布后，请固定已发布版本而不是使用 latest，这样 MCP 客户端就不会意外改变行为。

Claude Desktop

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@youtube-mcp/server@0.7.0", "serve"],
      "env": {
        "YOUTUBE_MCP_PROFILE": "default"
      }
    }
  }
}

在原生 Windows 上，使用 "command": "cmd" 并在参数前加上 "/c", "npx"。

Claude Code

claude mcp add youtube --scope user \
  --env YOUTUBE_MCP_PROFILE=default -- \
  npx -y @youtube-mcp/server@0.7.0 serve

Codex

codex mcp add youtube \
  --env YOUTUBE_MCP_PROFILE=default -- \
  npx -y @youtube-mcp/server@0.7.0 serve

等效的 Codex 配置：

[mcp_servers.youtube]
command = "npx"
args = ["-y", "@youtube-mcp/server@0.7.0", "serve"]

[mcp_servers.youtube.env]
YOUTUBE_MCP_PROFILE = "default"

一次可以添加多少内容

每次工具调用的硬性模式限制：

因此，单次提交的上限是 50 首歌曲。更长的列表通过每批 50 首的方式提交处理：先用第一批创建播放列表，然后在后续每次提交时传入其 target_playlist_id 以追加内容。已存在的重复项会被跳过并报告，而不会重复插入。

实际上，每日配额是更严格的限制。按照 Google 默认的每个项目每天 10,000 个单位的配额，一次 50 首歌曲的运行大约消耗：

这意味着大约每个项目每天只能创建一个 50 首歌曲的播放列表。同一天第二次完整运行将耗尽配额，并在插入过程中途失败。重复准备同一列表尤其昂贵：即使结果没有变化，搜索也会再次计费。

配额在美国太平洋时间午夜重置，这也是本地账本使用的日界点。

配额预期

youtube_quota_status 报告的是本地观测到的用量，而非 Google 的权威余额。通用单位和 search.list 调用是分开跟踪的，因为 Google 对搜索调用单独设置了默认的每日上限。

search.list 按其公布的 100 个单位计费，因此 general_units 反映的是实际消耗。0.5.0 之前的版本将其记录为 1 个单位，因此每次搜索少报了 99 个单位；当报告的数字看起来仍然很低时，写入可能已因配额被拒绝。如果您使用的是更早的版本，请升级。

配额值可能会变化。实现和发布工作必须核对当前官方费用表，而不是将本 README 中的数值视为永久常量。

故障排查

提交报告 status: "partial"，completed 为空，所有内容都在 pending 中。 播放列表已创建，但第一次插入被拒绝——最常见的原因是每日配额。不会盲目重试，因此不会写入重复条目。检查 youtube_quota_status，删除空播放列表，并在太平洋时间重置后重新运行。由于草稿是一次性的，重新运行需要重新执行 youtube_prepare_music_playlist。

login 在浏览器打开之前就失败了。 该配置文件没有存储客户端密钥。先运行 setup，并确认您处于预期的 YOUTUBE_MCP_PROFILE 中。

授权成功，但大约一周后停止工作。 处于“测试”状态的 Google OAuth 项目签发的刷新令牌会在七天后过期。发布同意屏幕或重新运行 login。

公共读取时出现 403。 服务器环境中缺少 YOUTUBE_API_KEY。它永远不会被持久化，因此必须在每次启动时都存在——包括 MCP 客户端配置的 env 块中。

认证模型

• 公共读取需要在进程环境中提供 YOUTUBE_API_KEY。

• 账户读取需要具有 youtube.readonly 范围的 OAuth。

• 播放列表创建和评论写入需要 youtube.force-ssl，因为 Google 不提供仅限播放列表的范围。

• 视频上传和生命周期管理需要 youtube.upload。它是单独请求的，如果配置文件在未包含该范围的情况下被授权，视频工具将拒绝工作。请将其添加到您的同意屏幕，并在上传前重新运行 login。

• 服务器通过严格的白名单来抵消 Google 范围的宽泛性：只有播放列表和播放列表条目的写入端点可被调用。

• 已安装应用使用授权码 + PKCE、随机 state，以及在 127.0.0.1 上使用随机端口的回环重定向。

• 普通 YouTube 账户不支持服务账户。

切勿提交 API 密钥、OAuth 客户端数据、访问令牌、刷新令牌、本地数据库、调试日志或 .env 文件。

字幕与分析

通用的公开转录文本获取不属于 v1 的一部分。官方的字幕下载端点受权限限制且费用高昂，因此不会使用非官方的抓取方式。所有者授权的字幕管理可能会在以后考虑。

YouTube Analytics 和 Reporting API 也被推迟了。它们需要单独的 OAuth、数据模型和操作行为，不应使最初以播放列表为重点的服务器复杂化。

开发

已实现的技术栈包括 TypeScript、Node.js 20.17+、ESM、官方 MCP TypeScript SDK、Zod 验证、对已批准的 Google 端点的直接类型化 REST 调用、用于本地配额/草稿/日志状态的 SQLite，以及用于 OAuth 刷新令牌的操作系统钥匙串适配器。

当前检查项：

npm run format:check
npm run lint
npm run typecheck
npm test
npm run build

实现应遵循 PLAN.md 中的阶段和验收门。代理特定的约束和完成定义见 AGENTS.md。Claude Code 应从 CLAUDE.md 开始。

项目状态

• 产品与安全架构

• 仓库开发说明

• TypeScript 包脚手架

• 公共读取工具

• OAuth 与配置文件

• 音乐匹配与预览

• 已确认的新播放列表创建

• 已预览的播放列表更新、重新排序、移除和删除

• 音乐草稿提交的现有播放列表目标 (0.5)

• 配额账本中正确的 search.list 通用单位核算 (0.5)

• 评论插入、回复、删除和审核 (0.6)

• 视频上传、元数据更新、删除和缩略图 (0.7)

• YouTube Analytics 报告 (0.8)

• 跨客户端集成测试

• 首次 npm 发布

许可证

根据 Apache License 2.0 许可。完整的许可证文本见 LICENSE。

参考

• Model Context Protocol

• YouTube Data API v3

• YouTube Data API quota costs

• Google OAuth for installed apps

• Claude MCP documentation

• Codex MCP documentation