youtube-analytics-mcp

一个 MCP 服务器，为 AI 助手提供你拥有的频道的完整 YouTube Analytics、Data v3 和 Reporting API 接口——包括同时管理多个频道。

大多数 YouTube MCP 服务器硬编码了一小撮指标字符串，因此只要问题超出其预设列表，不 fork 它们就无法回答。这个服务器反其道而行之：youtube_analytics_query 接受 reports.query 接受的所有参数，youtube_data_call / youtube_reporting_call 对其他两个 API 也是如此。预设只是之上的便捷功能，绝不是唯一的访问途径。

你需要自己准备 Google Cloud OAuth 客户端。本包不附带任何凭据，没有任何凭据经过第三方，一切都在本地通过 stdio 运行。

工具

每个数据工具都接受可选的 account，因此一次对话可以比较两个频道。

大型结果写入文件，而非经由模型返回

youtube_analytics_query、youtube_data_call 和 youtube_reporting_call 接受 outputPath（以及可选的 format：csv 或 json，否则根据扩展名推断）。指定后，完整结果写入磁盘，只返回摘要——行数、列数、字节大小、前三行。未指定时，超过 100 行的结果会被截断，并附上该选项的提示，因为将一千行的报告内联返回会消耗调用方的上下文窗口，而且到达时也无法阅读。

对于真正的大批量工作——每个视频的每一天、持续数月——请通过 youtube_reporting_call 使用 Reporting API：它可以生成可下载的每日 CSV 报告，包含 reports.query 单次调用无法返回的维度组合。

Related MCP server: YouTube MCP Server

设置

1. 一次 Google Cloud OAuth 客户端

• 创建或选择一个项目。

• APIs & Services → Library：启用 YouTube Analytics API、YouTube Data API v3 和 YouTube Reporting API。

• OAuth consent screen → Audience：将用户类型设置为 External（只有关联了 Workspace 组织时才提供 Internal）。在同一 Audience 页面上，在 Test users 下点击 + Add users，添加每个频道所有者的 Google 账户——包括你自己的。

  如果遗漏这一步，同意流程会失败，并显示 "… has not completed the Google verification process. The app is currently being tested and can only be accessed by developer-approved testers." 作为项目所有者并不会自动使你成为测试用户；你必须显式添加自己。

• 将发布状态设置为 In production。 这比看起来更重要。Google 指出：

  一个配置了外部用户类型 OAuth 同意屏幕且发布状态为“Testing”的 Google Cloud Platform 项目，会被签发 7 天到期的刷新令牌，除非请求的 OAuth 范围仅为姓名、电子邮件地址和用户配置文件的一部分。

  每个 YouTube 范围都是敏感范围，因此 Testing 应用会迫使你每周重新授权。

  请注意，对于这些范围，发布并不是简单的开关：控制台很可能会要求你提供演示视频，并在允许你离开 Testing 之前让应用接受 YouTube API 验证审核。对于个人工具来说这是实际的工作，而每周重新同意通常是更好的权衡。替代方案见下方 7 天授权限制。

• Credentials → Create credentials → OAuth client ID → Desktop app。 不是 Web application：此服务器每次运行都会监听一个随机的空闲回环端口，而 Web 客户端要求所有重定向 URI（包括端口）都事先注册。

• 下载 JSON。

2. 告诉服务器客户端在哪里

将其放入配置文件（参见 config.example.json）：

// %APPDATA%\youtube-analytics-mcp\config.json          (Windows)
// ~/Library/Application Support/youtube-analytics-mcp/  (macOS)
// ~/.config/youtube-analytics-mcp/config.json           (Linux)
{
  "client": { "client_id": "...", "client_secret": "..." }
}

运行 youtube-analytics-mcp --where 打印该目录。环境变量同样有效且优先级更高——YTMCP_CLIENT_ID + YTMCP_CLIENT_SECRET，或 YTMCP_CLIENT_FILE 指向 Google 下载的原始文件（{"installed": …} 包装会自动解包）。YTMCP_CONFIG_DIR 可重定位整个目录。

3. 授权每个频道

bun run auth                      # or: youtube-analytics-mcp --authorize
bun run auth -- --alias second    # name it yourself

你的浏览器会自动打开同意页面；URL 也会打印出来，用于无法打开浏览器的情况（SSH、容器、CI）。选择拥有该频道的 Google 账户并批准。对每个频道重复此操作——在浏览器中每次都选择不同的账户。账户以其 @handle 命名，除非你传入 --alias。

设置 YTMCP_NO_BROWSER=1 以永不启动浏览器，或向 youtube_authorize 工具传入 openBrowser: false 以仅对单次调用生效。

刷新令牌写入同一目录下的 accounts.json，与你手工编辑的 config.json 分开存放，因此你可能粘贴到 bug 报告中的文件永远不会是包含令牌的文件。在平台支持的情况下，两者都以 0600 权限写入。

你的助手也可以驱动此流程。youtube_authorize 会立即返回同意 URL，并在后台持续监听；youtube_authorize_status 报告其最终结果。它不会阻塞，因为同意所需时间取决于人的操作速度，而 MCP 客户端远在此之前就会放弃一次工具调用。URL 也会写入配置目录中的 pending-auth.txt，因为大多数客户端会丢弃服务器的 stderr，而无人能读的 URL 毫无用处。

4. 在你的 MCP 客户端中注册

Claude Code：

claude mcp add youtube-analytics --scope user -- bunx youtube-analytics-mcp

或手动写入任何客户端的 mcpServers 映射：

{
  "mcpServers": {
    "youtube-analytics": { "command": "bunx", "args": ["youtube-analytics-mcp"] }
  }
}

默认只读

更新视频、发布或审核评论、上传缩略图在真实频道上都是不可逆的操作，因此不会请求写入范围，非 GET 调用会被拒绝。要启用它们，请设置 YTMCP_ALLOW_WRITE=1 并重新授权——仅设置该标志无效，因为存储的令牌不带有该范围。

并发观看者，以及无人能猜到的查询形态

averageConcurrentViewers 和 peakConcurrentViewers 确实适用于已结束的直播，并且与 Studio 自身的数字完全一致。它们被广泛认为不存在，因为 API 几乎以所有形态拒绝它们——唯独一种除外：过滤器必须固定到单个视频 并且 dimensions 必须为 livestreamPosition。

没有任何错误提示缺失的维度，尤其是那个 500 错误，读起来像是指标本身有问题，而不是请求有误。youtube_concurrent_curve 会为你组装好这一切，并返回峰值、平均值以及完整的逐分钟曲线。

它真正无法提供的内容

youtube_capabilities 返回当前列表。以下两项都是通过请求指标并收到 Unknown identifier 来验证的，这正是 API 区分它从未听说过的名称与它知道但在这里无法提供的名称的方式：

• 直播聊天消息和反应总数。 仅 Studio 可用。liveChatMessages 是实时读取聊天，无法恢复已结束的聊天。

• 展示次数和展示点击率。 仅 Studio 可用，位于 Reach 标签页。

两件值得知道的事

不存在“自发布以来”的时间窗口。 Analytics API 纯粹基于日期范围，因此覆盖直播当天的窗口按构造就会返回该直播的直播观众。Studio 默认的按视频窗口排除了整个直播期间，这在分析直播时是一个既容易又代价高昂的陷阱。本 API 不会落入这个陷阱。

Analytics 配额是独立的。 Analytics 和 Reporting API 与 Data API v3 的每日单位预算分开计量，因此在此查询不会消耗实时聊天轮询所竞争的配额。这是基于它们是拥有各自控制台配额页面的独立 API 的强推断——并非实测。

开发

bun install
bun run dev          # start on stdio
bunx tsc --noEmit    # typecheck
bun run inspector    # MCP Inspector

MIT。

API 会滞后几天

最终确定的 Analytics 数据并非立即可用。于 2026-08-25 实测，按天维度的行一直覆盖到 08-22 便停止了：之前三天的会话根本没有返回任何行，而不是返回零行。对几小时前结束的直播进行查询，看起来会像一个没有流量的频道。

Studio 的 Web UI 有一条 API 未暴露的实时路径，因此当日报告仍必须来自 Studio。请将此服务器用于大约三天以前的所有数据，在那些数据上它远比在 Studio 中逐个视频点击要好得多。

7 天授权限制，以及为什么任何代码都无法绕过它

当 Cloud 项目的发布状态为 Testing 且用户类型为 External 时，Google 会在 7 天后撤销刷新令牌，除非请求的范围仅限于姓名、电子邮件和个人资料。每个 YouTube 范围都是敏感范围，因此该例外在此永远不适用。

这无法通过自动化消除。 7 天是施加在 刷新 令牌上的。铸造新令牌需要有人在浏览器中批准同意屏幕——这才是同意的含义，而不是可以绕过的工程缺口。更频繁地刷新访问令牌对此毫无影响。

此服务器所做的替代安排：

• youtube_accounts 报告每项授权的 ageDays，并从第 5 天开始发出警告。

• 已过期的授权会以一条指明原因和解决办法的消息失败，而不是赤裸裸的 invalid_grant。

• youtube_refresh_tokens（或从 CLI 使用 --refresh）将每项授权作为健康检查加以行使。这也是一种对冲：尚未确定 7 天时钟是从签发时绝对计时，还是在使用时顺延。如果会顺延，通过调度器每天运行一次即可无限期保持授权有效；如果不会，该调用也几乎不花费什么。无论如何都值得运行。

• 重新同意只需一次 youtube_authorize 调用，它会自行打开浏览器——大约十五秒。

真正的解决办法，按成本排序：

1. 发布状态 → 正式版。 免费，且授权不再过期。对于敏感的 YouTube 授权范围，Google 可能要求你提供演示视频并通过验证审核，然后才允许发布，这对个人工具来说确实是不小的工作量。

2. 内部用户类型。 没有 7 天限制，也无需验证，但该选项仅在项目属于 Google Workspace 组织（付费订阅）时才存在。

3. 以每周重新授权的方式正式上线。 对于单用户工具来说，这通常是正确的选择。