youtube-organic-mcp

youtube-organic-mcp

用于 YouTube 自然流量分析 的 MCP 服务——通过 YouTube Data API v3 和 YouTube Analytics API v2 获取频道数据、视频表现、观看时长和观众互动情况。

专为 Claude Code 和任何兼容 MCP 的 AI 工具打造。让你的 AI 助手直接以只读方式访问你自己的频道自然流量数据——订阅者、观看次数、观看时长、单个视频的互动数据以及每日趋势。

这是 Rex Jones 打造的 The SEO Engine 工具集的一部分，提供面向代理机构和企业的 AI 驱动型 SEO 和社交媒体工具。

为什么要开发这个工具

• 当时没有好用的开源 YouTube 自然流量 MCP 服务。 广告类 MCP 服务很多；自然流量频道分析工具则一个都没有。
• 在主流平台中，YouTube 的自然流量 API 提供的数据最丰富。 观看时长、平均观看时长、订阅者增减、流量来源——这些数据都无需经过数周的审核即可获取。
• 重用现有的 Google OAuth。 如果你已经在使用 GA4 / GSC / Google Ads MCP 服务，同一个 OAuth 客户端也适用于此处。

工具

工具	说明
list_accounts	列出已配置的频道和默认频道
get_channel_info	频道资料 + 累计统计数据（订阅者、总观看次数、视频数量、上传内容播放列表）
get_videos	分页列出上传的视频，并显示每个视频的观看次数、点赞数、评论数和时长
get_video_details	获取指定视频 ID 的详细信息（最多可批量处理 50 个）
get_channel_analytics	指定日期范围内的频道分析数据：观看次数、观看时长、平均观看时长 / 百分比、新增 / 流失订阅者、点赞数、评论数、分享数——可按天查看
get_video_analytics	指定日期范围内单个视频的相同指标

所有工具都接受可选的 account 参数，以支持多账号配置。

开始连接

第 1 步：启用 API

在 Google Cloud Console 中（任何项目均可——你可以重用现有项目），启用 YouTube Data API v3 和 YouTube Analytics API。

第 2 步：获取刷新令牌

创建一个类型为 Desktop app 的 OAuth 客户端，并下载其 client_secret JSON。然后运行辅助程序（需要 pip install google-auth-oauthlib）：

python3 scripts/get_youtube_token.py /path/to/client_secret.json my-channel

使用拥有该频道的 Google 账号进行授权（如果出现提示，请选择品牌账号）。程序会打印出需要填入配置的三个 YOUTUBE_* 值，并将它们写入 .youtube_account.json（已加入 gitignore）。

第 3 步：配置

将以下内容添加到 Claude Code MCP 设置中：

{
  "mcpServers": {
    "youtube-organic": {
      "command": "node",
      "args": ["/path/to/youtube-organic-mcp/dist/index.js"],
      "env": {
        "YOUTUBE_CLIENT_ID": "your_client_id.apps.googleusercontent.com",
        "YOUTUBE_CLIENT_SECRET": "your_client_secret",
        "YOUTUBE_REFRESH_TOKEN": "1//your_refresh_token"
      }
    }
  }
}

或者将 YOUTUBE_ACCOUNTS 设置为包含多个频道的 JSON 数组（参见 .env.example）。

架构

src/
  index.ts          # MCP server entry point, tool registration
  accounts.ts       # Multi-account resolution (client_id/secret/refresh_token)
  client.ts         # OAuth token minting + Data/Analytics API HTTP client
  types.ts          # TypeScript interfaces for API responses
  tools/
    channel.ts      # get_channel_info + uploads-playlist resolver
    videos.ts       # get_videos, get_video_details
    analytics.ts    # get_channel_analytics, get_video_analytics

• 零外部 HTTP 依赖项——使用原生 fetch（Node 18+）
• 自动刷新身份验证——使用刷新令牌生成访问令牌，并按进程缓存
• 支持多账号——通过一个服务监控多个频道

许可证

MIT