YouTube MCP Server

一个开源的 Model Context Protocol (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 内容视为不可信数据。

• 跨平台 TypeScript 支持，要求 Node.js 20.17 或更高版本。

v1 规划范围

读取工具

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

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

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

• 返回提供方分页令牌，以进行显式的无状态分页。

音乐播放列表工作流程

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

• 搜索并排序可能的 YouTube 音乐视频匹配项。

• 显示歧义和备选方案，而不是默默选择匹配不佳的结果。

• 将明确选中的匹配项提交到新播放列表。计划支持以现有播放列表为目标。

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

播放列表管理

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

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

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

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

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

播放列表管理之外的写入操作——上传、评论、评分、订阅和频道更改——被有意排除在范围之外。

设置

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 和随机的 state 值。当该配置文件未存储客户端密钥时，它会在打开浏览器之前立即失败。

要撤销并删除已存储的凭据：

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.4.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.4.0 serve

Codex

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

等效的 Codex 配置：

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

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

一次可以添加多少

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

因此，一次播放列表创建的上限是 50 首歌曲。由于准备好的草稿目前还不能提交到现有播放列表，超过 50 首歌曲的列表必须拆分为多个播放列表。

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

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

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

配额预期

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

[!WARNING] 已知限制：本地账本将每次 search.list 记录为 1 个通用单位加 1 次搜索调用，而 Google 对其收取 100 个单位。因此，大量搜索后，general_units 会在每次搜索上低估 99 个单位的真实消耗量，写入可能因配额被拒绝，而报告的数字看起来仍然很低。在此问题修正之前，请将 search_calls 计数视为有意义的信号。预览仍会为提交的写入部分显示 estimated_commit_units 数值。

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

故障排查

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

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

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

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

身份验证模型

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

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

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

• 服务器通过严格的端点允许列表来抵消 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 中所述阶段和验收门。Agent 特定的约束和完成定义见 AGENTS.md。Claude Code 应从 CLAUDE.md 开始。

项目状态

• 产品和安全架构

• 仓库开发说明

• TypeScript 包脚手架

• 公共读取工具

• OAuth 和配置文件

• 音乐匹配和预览

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

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

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

• 修正配额账本中 search.list 的通用单位核算

• 跨客户端集成测试

• 首次 npm 发布

许可证

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

参考资料

• Model Context Protocol

• YouTube Data API v3

• YouTube Data API 配额费用

• 用于已安装应用的 Google OAuth

• Claude MCP 文档

• Codex MCP 文档