YouTube Studio MCP

一个用于审计和提升 YouTube 频道可发现性的 MCP 服务器。

它可将任何支持 MCP 的 AI 代理连接到你自己频道的数据：目录、Analytics API 指标、留存曲线、站内搜索词，以及只有 Studio CSV 导出才能暴露的展示次数和点击率。然后，它根据可挽回观看次数（而非点击率）对值得修复的内容进行排序——参见表现不佳视频的排序方式。

八个工具：auth_status、list_videos、get_video、query_analytics、get_search_terms、get_retention_curve、import_studio_data 和 find_underperformers。

一切都是只读且本地的：SQLite 缓存、你的 OAuth 令牌和你的 Studio 导出文件永远不会离开你的机器。

要求

• Node.js ≥ 22

• 一个拥有该 YouTube 频道的 Google 账号

Related MCP server: YouTube MCP Server

设置

1. 创建 Google Cloud 项目并启用 API

1. 前往 https://console.cloud.google.com/ 并创建一个项目。

2. 启用 YouTube Data API v3 和 YouTube Analytics API。 （两者都在实际使用中：Data API 支持目录同步和 list_videos/get_video，Analytics API 支持 query_analytics、get_search_terms 和 get_retention_curve。Google Cloud Console 只允许你为已启用的 API 添加同意屏幕范围，所以在下一步之前请同时启用两者。）

2. 配置 OAuth 同意屏幕

1. 前往 API 和服务 → OAuth 同意屏幕。

2. 选择外部并填写必填字段。

3. 添加以下范围：

   • https://www.googleapis.com/auth/yt-analytics.readonly

   • https://www.googleapis.com/auth/youtube.readonly

   • https://www.googleapis.com/auth/youtube.force-ssl

重要——将应用发布到生产环境。 当应用处于测试状态时，Google 会在 7 天后使刷新令牌过期，因此你必须每周重新认证。点击发布应用。 应用仍保持未验证状态，这没问题：你是唯一用户，并且访问的是自己的数据。你只会看到一次"未验证应用"警告——选择高级 → 前往（应用名称）。

3. 创建 OAuth 客户端

1. API 和服务 → 凭据 → 创建凭据 → OAuth 客户端 ID。

2. 应用类型：桌面应用。

3. 下载 JSON 文件。

4. 安装并认证

npm install
npm run build

将下载的 OAuth 客户端 JSON 保存为服务器配置目录中的 credentials.json（如果目录不存在，请先创建）：

# Linux/macOS — adjust the source filename to match what Google actually
# named your download (it starts with "client_secret_")
mkdir -p ~/.config/youtube-studio-mcp
mv ~/Downloads/client_secret_*.json ~/.config/youtube-studio-mcp/credentials.json

# Windows (PowerShell) — same caveat about the source filename
New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\youtube-studio-mcp" | Out-Null
Move-Item "$env:USERPROFILE\Downloads\client_secret_*.json" "$env:USERPROFILE\.config\youtube-studio-mcp\credentials.json"

然后运行：

node dist/index.js auth

这会自动打开你的浏览器。在那里授权，令牌将保存到 <config dir>/tokens.json。在 Linux/macOS 上，该文件以仅所有者权限（chmod 600）写入；Windows 没有等效的文件权限位，因此该步骤在那里是空操作——请依赖你用户账户的正常文件保护。

如果没有打开浏览器，该命令还会将授权链接写入 <config dir>/authorize-url.txt——打开该文件并点击链接。不要从终端手动复制 URL：它约有 520 个字符，会跨多行换行，截断的副本会在 Google 端失败并显示误导性错误 Required parameter is missing: response_type（缺失的参数在被截断的部分中，而不是在我们构建的请求中）。

设置 YTMCP_HOME 可覆盖配置目录（例如用于第二个频道或测试环境）。它会替换整个 ~/.config/youtube-studio-mcp 路径，因此 credentials.json、tokens.json 和 SQLite 缓存都会随之移动。

5. 向你的 AI 代理注册服务器

该服务器通过 stdio 使用标准 MCP 协议，因此任何支持 MCP 的客户端都可以运行它。每种情况下你都需要一件事：本仓库中 dist/index.js 的绝对路径。

大多数客户端共享相同的 JSON 结构。替换为你自己的路径：

{
  "mcpServers": {
    "youtube-studio": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-studio-mcp/dist/index.js"]
    }
  }
}

两个客户端使用不同的结构。

VS Code / GitHub Copilot — .vscode/mcp.json，键为 servers，而非 mcpServers：

{
  "servers": {
    "youtube-studio": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/youtube-studio-mcp/dist/index.js"]
    }
  }
}

OpenAI Codex CLI — ~/.codex/config.toml，使用 TOML 而非 JSON：

[mcp_servers.youtube-studio]
command = "node"
args = ["/absolute/path/to/youtube-studio-mcp/dist/index.js"]

编辑配置后重启代理。让它运行 auth_status：它应显示你的频道名称并报告剩余配额。如果它报告 Authenticated: NO，请重新运行 node dist/index.js auth。

如果你的客户端未列出，请在其设置中查找"MCP"——上述命令和参数就是它们所需的全部内容。配置路径在不同版本之间可能会变化，因此如果这里的路径不存在，请查看你自己客户端的文档。

关于代理行为的说明

每个工具都标注了 readOnlyHint: true，因此会显示该提示的代理不会提示确认写入操作。此服务器中的任何内容都不会修改你的频道——将元数据写回是后续阶段。

list_videos 除非要求同步，否则从本地缓存提供服务，而 find_underperformers 和 import_studio_data 完全不访问网络。只有显式同步和 Analytics 查询会消耗配额，这一点很重要，因为代理会进行探索：代理调用 list_videos 二十次不花费任何成本，而二十次目录同步会耗尽一天的预算。auth_status 会报告剩余配额。

工具

list_videos 完全从本地 SQLite 缓存提供服务，除非你传入 sync: true——纯读取（按 Shorts/长视频、观看次数、发布日期、标题筛选或排序）不消耗配额。如果尚未同步任何内容，它会告诉你使用 sync: true 再次调用，而不是返回空列表。

get_search_terms 和 get_retention_curve 按日期窗口缓存其结果（参见下面的配额）；query_analytics 不缓存，始终进行实时调用。get_search_terms 最多返回 25 行——Google 将底层报告限制在该数量，因此更宽的日期范围会改变哪些词排在前 25 名，而不是返回多少行。

配额

YouTube 每天授予 10,000 个单位，外加单独的每天 100 次 search.list 调用。服务器会跟踪两者并保留储备（500 个单位、10 次搜索调用），以便批量操作不会使交互式工具不可用。配额在太平洋时间午夜重置，这正是 auth_status 所报告的。

完整目录同步（带 sync: true 的 list_videos）会进行一次 channels.list 调用，然后分页获取上传播放列表（playlistItems.list，每页 50 个视频），并批量获取视频详情（videos.list，每次调用 50 个 ID），每次调用消耗 1 个单位。总计为 1 + ceil(videos/50) + ceil(videos/50) 个单位——对于一个 100 个视频的频道约为 5 个单位。

YouTube Analytics API 在 Cloud Console 中有自己独立于 Data API 10,000 个单位的按项目配额。Analytics 调用以零单位成本记录在本地账本中，因此 auth_status 不会显示它们消耗你的 Data API 预算。

搜索词结果和留存曲线按日期窗口缓存，因为底层报告返回的是某个范围内的排名前 N 项，而非按天的行。使用相同日期重复调用将从缓存提供服务；传入 refresh: true 可重新查询。

导入展示次数和点击率

impressions 和 impressionClickThroughRate 不存在于 YouTube Analytics API 中——它们仅限 Studio。要获取它们：

1. YouTube Studio → Analytics → 高级模式（右上角）

2. 确保展示次数和展示次数点击率列可见——导出仅包含当前屏幕上的列

3. 导出 → 逗号分隔值 (.csv)——你会得到一个包含三个文件的 zip 压缩包

4. 解压后，使用文件夹路径运行 import_studio_data

import_studio_data 仅从磁盘读取文件——它从不调用 YouTube Data API 或 Analytics API，因此无需认证且不消耗 API 配额。

日期窗口从文件夹名称中读取（Studio 的命名格式类似 Contenido 2010-01-26_2026-08-09 Channel）。要覆盖它，请同时传入 rangeStart 和 rangeEnd（YYYY-MM-DD）——只提供其中一个会被拒绝并显示验证错误，而不是静默回退到文件夹名称窗口，因为那可能在没有警告的情况下将数据放到错误的日期下。两个日期都必须是真实的日历日期（2026-13-45 会被拒绝，而不是滚动进位），且 rangeStart 不得晚于 rangeEnd。

展示次数和点击率是整体范围的汇总。 在导出的三个文件中，只有按视频统计的表（Datos de la tabla.csv / Table data.csv）包含展示次数和点击率，并且每个视频一行，汇总整个日期范围——导出中没有任何按日点击率数据。按日文件（Datos del gráfico.csv / Chart data.csv）和频道总计文件（Totales.csv / Totals.csv）只包含观看次数。因此，跨时间比较意味着导入多个不同范围的导出文件，而不是对单个文件进行切片。

import_studio_data 接受导出文件夹或特定的 CSV 路径。指向文件夹时，它会自动找到表文件。直接指向另外两个文件之一时，导入会被直接拒绝：CSV 的头部会明确告诉你它是三个报告中的哪一个（reportType 是 table、chart 或 totals——参见 src/studio/csvSchemas.ts），并且只有 table 包含此导入器可以存储的内容。图表文件确实有视频 ID，因此天真的导入会静默成功，同时将展示次数/点击率覆盖为 NULL，并将观看次数覆盖为最后一天的数字而不是范围总计；总计文件根本没有视频 ID。两者都会在写入任何内容之前被拒绝，并附上一条消息，指明应指向 Datos de la tabla.csv / Table data.csv 文件。

不再公开的视频的行会被存储并报告为未匹配；这是预期行为，不是错误。

Shorts

一个视频只有在180秒或更短 并且 发布于2020-09-14（Shorts 推出的那一天）或之后，才被计为 Short。

仅凭时长是不够的。在一个天然较短的长视频目录中——音乐视频、剪辑、预告片——仅凭时长的规则会大规模误分类。对一个 2020 年前已休眠的频道进行实时验证，发现其目录中约 70% 被标记为 Shorts，而每一个都是误报：该频道最新的上传时间比 Shorts 推出早了好几个月，因此其中不可能有一个是真正的 Shorts。

find_underperformers 通过其 cohort 参数读取此标志。传递 cohort: 'short' 或 cohort: 'long' 会将基线限制在该目录的一半，因此 Shorts 和长视频只与同类进行比较。默认值 cohort: 'all' 不进行这种分段——它将两者合并为一个混合基线。在已经是一个群体的目录上（此用户的真实情况，完全是长视频），合并是无操作，但在混合目录上，默认值会混合两个具有不同典型点击率的人群；显式传递 cohort 以进行分段。视频上的错误标志会产生看似合理的错误结果而不是明显的错误，这就是为什么发布日期的保护措施很重要。

表现不佳者如何排名

find_underperformers 按可恢复观看次数排名，而不是按点击率排名：

recoverable views = impressions x (baseline CTR - video CTR) / 100

这是对视频在频道自身基线下本应获得的观看次数的估计——值得采取行动的量。仅按点击率排名会产生误导，具体有三种方式：

• 展示次数集中。 频道的大部分展示次数集中在少数视频中，因此“最差点击率”和“最大机会”几乎是互不相交的集合。比率最差的视频往往是几乎没有人看到的视频。

• 零展示次数通过除法产生 0% 的点击率，而不是通过表现。 升序排序会把每个从未被展示的视频放在待修复列表的顶部，这完全颠倒了。

• 频道上最高的点击率通常是一个极小的分母——恰好转化的少数展示次数。这是被当作胜利展示的噪声。

因此有两条规则。低于展示次数下限的视频被报告为数据不足，永远不会被排名为表现不佳者。基线是展示次数加权的，因为未加权的平均值会被低流量视频主导，几乎无法描述频道实际获得的流量。

每个机会都有类型。weak_metadata 表示元数据分数足够低，是需要首先修复的问题；low_ctr 表示元数据已经良好，缩略图或标题框架是杠杆点。

开发

npm test          # unit tests, no network
npm run typecheck
npm run build

npm run typecheck 运行两个项目：tsconfig.json（src/**，构建）和 tsconfig.test.json（src/** + test/** + vitest.config.ts，仅 noEmit）。使用 npm run typecheck:test 仅运行测试项目。Vitest 本身仅通过 esbuild 剥离类型，不进行类型检查，因此 npm run typecheck 才是真正捕获测试文件中类型错误的方式。