youtube-analytics-mcp

一个本地、只读的 MCP 服务器，让 Claude 能访问你的 YouTube 频道的私有分析数据——观看次数、观看时长、留存率、订阅者、流量来源、受众分布、收入以及缩略图展示次数/点击率。不仅仅是任何公共 API 密钥都能看到的内容。

该服务器中的任何功能都无法编辑、上传、发布或删除你频道上的任何内容。完整安全审查请参阅 SECURITY.md。

系统要求

• Node.js 22 及以上

• 一个 Google 账号，须拥有（或管理）你想获取数据的 YouTube 频道

• macOS、Linux 或 WSL（npm run auth 浏览器流程使用 open 命令）

Related MCP server: YouTube MCP Server

设置清单

请按顺序完成。第 1–4 步在 Google Cloud Console 中完成；第 5–8 步在你自己的机器上完成。

1. 创建 Google Cloud 项目

前往 console.cloud.google.com 并创建一个新项目（或选择现有的、你熟悉且愿意使用的项目）。

2. 启用三个 API

在你的项目中，前往 APIs 与服务 → 库，并启用以下每一项：

• YouTube Data API v3

• YouTube Analytics API

• YouTube Reporting API（仅用于缩略图展示次数/点击率——参见 下文）

3. 配置 OAuth 同意屏幕

前往 APIs 与服务 → OAuth 同意屏幕。

• 用户类型：外部（除非你拥有 Google Workspace 账号，此时“内部”也可用）

• 填写必填的应用名称 / 支持邮箱字段

• 在提示时添加 Analytics 范围（或跳过——应用会直接请求这些权限，此屏幕只需存在即可）

• 将应用发布到生产环境。这是人们经常跳过、然后碰壁的一步：处于“测试”模式的应用仅允许来自你明确添加为测试用户的账号登录，并且其刷新令牌会在 7 天后过期，这意味着你每周都必须重新执行第 6 步。对于个人工具，不提交 Google 的验证审核就发布到生产环境是可以的——登录时 Google 会显示“未经验证的应用”警告，你点击 高级 → 前往 [你的应用名称]（不安全） 即可继续。这对于你自己的应用是预期行为，也是安全的。

4. 创建 OAuth 凭据

前往 APIs 与服务 → 凭据 → 创建凭据 → OAuth 客户端 ID。

• 应用类型：桌面应用

• 给它取任意名称

• 复制生成的 客户端 ID 和 客户端密钥——你将在第 5 步用到它们。

这里无需注册重定向 URI；本服务器会在认证时绑定一个本地临时端口，Google 支持桌面客户端的回环地址。

5. 安装并构建

git clone <this-repo-url>
cd youtube-analytics-mcp
npm install
npm run build

6. 配置你的凭据

cp .env.example .env

编辑 .env 并粘贴第 4 步获得的客户端 ID 和客户端密钥：

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

.env 已被 gitignore——它永远不会被提交到仓库。可选设置：

• GOOGLE_API_KEY —— 并非必需，除非你自行扩展服务器，否则留空即可。

• REVENUE_CURRENCY —— 默认 USD。如果你希望以其他货币（例如 BRL）查看收入数字，可设置为你的 AdSense 结算货币；Google 会自行转换。

7. 认证

npm run auth

这会在 Google 上打开浏览器登录流程，并将刷新令牌存储在 ~/.youtube-analytics-mcp/token.json（权限仅限你的用户，绝不会出现在仓库中）。你只需执行一次——之后服务器会自动刷新访问令牌。

验证是否成功：

npm run auth:status

你应该看到 Authenticated 以及你的频道名称。

8. 将其指向 Claude Code

在 MCP 配置中添加以下内容，使用此项目 dist/index.js 的绝对路径：

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

重新启动 Claude Code（或重新加载 MCP 服务器）后，你应该能看到下方列出的工具。

可用工具

关于展示次数和点击率的说明

YouTube 不会通过交互式 Analytics API（reports.query）在任何维度/筛选器组合下暴露缩略图展示次数或点击率——这是经过验证得出的结论，并非仅凭文档猜测。这些数据只存在于 YouTube 的批量“展示报告”中，这是一个单独的异步作业 API。

1. 首次调用 get_impressions_and_ctr 时，会向 Google 注册一个批量报告作业。

2. Google 需要 24–48 小时 生成第一份报告，之后大约会持续生成新的报告。

3. 每次调用 get_impressions_and_ctr（或按展示次数/点击率排序的 get_top_videos）都会将报告同步到本地缓存 ~/.youtube-analytics-mcp/token.json（实际为 ~/.youtube-analytics-mcp/impressions_cache.json），然后从该缓存返回结果。

在报告生成前，这些工具会返回 impressions: 0、ctr: 0，并附带一条 note 说明原因。这是正常现象，并非错误。

故障排查

• npm run auth 报错或无法登录：你的 OAuth 同意屏幕可能仍处于“测试”模式。回到第 3 步，将你的 Google 账号添加为测试用户，或直接将应用发布为“已发布”状态。

• NotAuthenticatedError 错误：运行 npm run auth。

• 收入数据始终为全零或不可用：频道可能未启用获利功能，或确实没有收入。工具永远不会编造收入——请检查 available 字段是否为 true；如果你的频道已获利但仍显示不可用，请确认 REVENUE_CURRENCY 设置是否正确。

• get_impressions_and_ctr 或按展示次数排序的 get_top_videos 返回空结果：检查响应中的 earliestDate 字段。如果它显示 null，则表明首次调用后报告尚未生成。

测试

npm test

安全性

请参阅 SECURITY.md 进行完整的安全审查。