kirbah-mcp-youtube

YouTube Data MCP 服务 (@kirbah/mcp-youtube)

专为 AI Agent 打造的生产级 YouTube Data MCP 服务。

与那些会向大模型塞入冗余数据的常规 API 封装不同，这个服务会精简 YouTube 冗长的数据负载。它旨在大幅节省上下文窗口令牌，通过缓存保护每日 API 配额，并可靠运行，不会破坏你的工作流。

为什么选择这个服务？

大多数 MCP 服务都是周末项目。@kirbah/mcp-youtube 专为可靠、日常且经济高效的 Agent 工作流打造。

🎯 想获得对自己频道的反馈，而不只是原始数据？ 不妨看看 CreatorLens——一款基于此 MCP 构建的配套 Claude Skill，它运用真实策略师的框架，而不只是数字，诊断常见的增长问题（薄弱的 开场、糟糕的缩略图、播放量停滞的视频）。

📉 1. 最多节省 87% 的令牌（和上下文窗口）

原始 YouTube API 会返回庞大的 JSON 数据负载，其中包含大模型不需要的嵌套 eTag、冗余缩略图和本地化数据。此服务会对数据进行结构化处理，让大模型只获得推理所需的信息，不多也不少。

%%{init: { "theme": "base", "themeVariables": { "xyChart": { "plotColorPalette": "#ef4444, #22c55e" } } } }%%
xychart-beta
    title "Token Consumption (Lower is Better)"
    x-axis ["getVideoDetails", "searchVideos", "getChannelStats"]
    y-axis "Context Tokens" 0 --> 1200
    bar "Raw YouTube API" [854, 1115, 673]
    bar "MCP-YouTube (Optimized)" [209, 402, 86]

API 方法	原始 YouTube 令牌	MCP-YouTube 令牌	令牌节省量	数据大小
getChannelStatistics	673	86	约少 87%	1.9 KB ➔ 0.2 KB
getVideoDetails	854	209	约少 75%	2.9 KB ➔ 0.6 KB
searchVideos	1115	402	约少 64%	3.4 KB ➔ 1.2 KB

（想进一步了解？你可以在 examples 文件夹中对比原始 API 响应与优化后的输出。）

🛡️ 2. 保护你的 API 配额（智能缓存）

YouTube Data API 有严格的每日限额（10,000 个配额单位）。如果你的大模型陷入循环或重复提问，常规服务会在几分钟内耗尽 API 限额。 此服务包含可选的 MongoDB 缓存层。如果你的 Agent 两次请求同一视频详情或搜索相同的热门视频，服务会从缓存中返回结果——不消耗任何 API 配额点数。

🏗️ 3. 生产级且积极维护

厌倦了 MCP 工具导致 AI 客户端崩溃？这个服务是可靠的依赖项：

• **97% 测试覆盖率：**经过全面的单元测试（请查看 Codecov 徽章）。
• **零 Lint 错误/警告：**强制执行严格、整洁的代码规范（npm run lint 可 100% 通过）。
• **主动安全维护：**通过自动化 Dependabot 修补，确保底层库不会遗留已知漏洞。
• **严格的类型安全：**采用 Zod 验证和稳健的 MCP TypeScript Starter 架构构建。

---

快速开始：安装

🟢 零配置模式（无需 API 密钥）

**只想获取转录文本？**无需任何配置，即可立即使用此服务！安装后即可开始使用。稍后添加 YouTube API 密钥，即可解锁深度搜索和分析功能。

安装此服务最简单的方法，是点击 Glama 服务页面上的 “添加到 Claude Desktop” 按钮。

如果要手动配置（例如，在 Cursor 中），只需添加以下最低限度的配置：

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@kirbah/mcp-youtube"]
    }
  }
}

✨ **提示：**在零配置模式下，你可以直接让 AI“读取 youtube://transcript/{videoId} 的转录文本”！

🟡 手动配置（解锁全部功能）

如果你想手动配置 MCP 客户端（例如 Claude Desktop 或 Cursor），请将以下内容添加到配置文件中：

1. 获取 YouTube Data API v3 密钥（请参阅下方的设置说明）。
2. （强烈推荐）获取免费的 MongoDB 连接字符串，以启用节省配额的缓存功能。

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@kirbah/mcp-youtube"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_YOUTUBE_API_KEY_HERE",
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:[email protected]/youtube_niche_analysis"
      }
    }
  }
}

（Windows PowerShell 用户：如果 npx 失败，请尝试使用 "command": "cmd" 和 "args": ["/k", "npx", "-y", "@kirbah/mcp-youtube"]。）

下一步：添加技能

连接服务后，可以试试 CreatorLens—— 这是专为此 MCP 构建的 Claude 技能，可将原始 YouTube 数据转化为增长诊断 （薄弱的开场、包装策略、细分领域定位疑虑、形式调整）。

主要功能

• **优化的视频信息：**使用高级筛选条件搜索视频。获取详细元数据、统计数据（观看次数、点赞数等）和内容详情，所有数据都经过结构化处理，尽可能减少令牌占用。
• **高效的转录文本管理：**获取视频字幕，支持多种语言，非常适合大模型进行内容分析。
• **深入的频道分析：**获取简明的频道统计数据（订阅者数、观看次数、视频数量），并发现频道的热门视频，避免数据臃肿。
• **精简的趋势发现：**按地区和类别查找热门视频，并获取可用视频类别列表，优化数据以便 AI 快速处理。
• **专为 AI 设计的结构：**所有响应都经过设计，易于解析，并可立即供语言模型使用。
• **高效的评论获取：**获取视频评论，可精细控制结果和回复的数量，优化后适用于情感分析和反馈提取。

可用工具

此服务提供以下 MCP 工具，每个工具都旨在返回经过令牌优化的数据：

工具名称	描述	参数（详情请参阅工具 schema）
getVideoDetails	获取多个 YouTube 视频的精简详细信息，包括元数据、统计数据、互动比率和内容详情。	videoIds（字符串数组）
searchVideos	根据查询字符串搜索视频或频道，并提供多种筛选选项，返回简洁的结果。	query（字符串）、maxResults（可选数字）、order（可选）、type（可选）、channelId（可选）等。
getTranscripts	获取多个视频的节省 token 的字幕，并可选择获取全文或关键片段（片头／片尾）。	videoIds（字符串数组）、lang（可选语言代码字符串）、format（可选枚举：'full_text'、'key_segments'，默认值为 'key_segments'）
getChannelStatistics	获取多个频道的精简统计数据（订阅者数量、观看次数、视频数量、创建日期）。	channelIds（字符串数组）
getChannelTopVideos	获取频道表现最佳的视频列表，包含精简详情和互动比率。	channelId（字符串）、maxResults（可选数字）
getTrendingVideos	获取指定地区的热门视频列表，并可选指定类别；结果包含精简详情和互动比率。	regionCode（可选字符串）、categoryId（可选字符串）、maxResults（可选数字）
getVideoCategories	获取指定地区可用的 YouTube 视频类别（ID 和标题），仅提供必要数据。	regionCode（可选字符串）
getVideoComments	获取 YouTube 视频的评论。支持排序、限制结果数量，以及为每条评论获取少量回复。	videoId（字符串）、maxResults（可选数字）、order（可选）、maxReplies（可选数字）、commentDetail（可选字符串）
findConsistentOutlierChannels	识别在特定细分领域中持续表现异常的频道。需要 MongoDB 连接。	niche（字符串）、minVideos（可选数字）、maxChannels（可选数字）

关于输入参数及其说明的详细信息，请参阅 src/tools/ 目录下各工具配置文件中的 inputSchema（例如 src/tools/video/getVideoDetails.ts）。

API 配额成本说明： 大多数工具的效率都很高。getVideoDetails、getChannelStatistics 和 getTrendingVideos 每次调用仅消耗 1 个单位。getTranscripts 工具不消耗 API 配额。新增的 getVideoComments 工具有可变成本：基础调用消耗 1 个单位；但如果请求回复（将 maxReplies 设置为大于 0 的值），则每个获取了回复的顶级评论会额外消耗 1 个单位。基于搜索的工具成本最高：searchVideos 消耗 100 个单位，getChannelTopVideos 消耗 101 个单位。

高级用法和本地开发

如果你想贡献代码、修改服务，或在 MCP 客户端托管环境之外本地运行：

先决条件

• Node.js（版本要求见 package.json 的 engines 字段，目前为 >=22.0.0）
• npm（通常随 Node.js 一起安装）
• YouTube Data API v3 密钥（参见 YouTube API 设置）

本地设置

1. 克隆代码仓库：

   git clone https://github.com/kirbah/mcp-youtube.git
   cd mcp-youtube
   

2. 安装依赖：

   npm ci
   

3. 配置环境： 复制 .env.example，在根目录下创建 .env 文件：

   cp .env.example .env
   

   然后编辑 .env，添加你的 YOUTUBE_API_KEY：

   YOUTUBE_API_KEY=your_youtube_api_key_here
   MDB_MCP_CONNECTION_STRING=your_mongodb_connection_string_here
   

开发脚本

# Run in development mode with live reloading
npm run dev

# Build for production
npm run build

# Run the production build (after npm run build)
npm start

# Lint files
npm run lint

# Run tests
npm run test
npm run test -- --coverage # To generate coverage reports

# Inspect MCP server using the Model Context Protocol Inspector
npm run inspector

使用 MCP 客户端进行本地开发

要让 MCP 客户端运行你的_本地开发版本_（而不是已发布的 NPM 包）：

1. 确保 package.json 中有一个用于启动且不启用监视的脚本，例如：

   "scripts": {
     "start:client": "tsx ./src/index.ts"
   }
   

2. 配置 MCP 客户端以启动此本地脚本：

   {
     "mcpServers": {
       "youtube_local_dev": {
         "command": "npm",
         "args": ["run", "start:client"],
         "working_directory": "/absolute/path/to/your/cloned/mcp-youtube",
         "env": {
           "YOUTUBE_API_KEY": "YOUR_LOCAL_DEV_API_KEY_HERE"
         }
       }
     }
   }
   

   关于上方 env 配置块的说明：在客户端配置的 env 配置块中直接设置 YOUTUBE_API_KEY，是提供 API 密钥的一种方式。或者，如果服务能根据 working_directory 正确加载其 .env 文件，只要项目根目录下的本地 .env 文件包含 YOUTUBE_API_KEY，就不一定需要在客户端的 env 配置块中指定它。working_directory 路径必须是正确的绝对路径，服务才能找到其 .env 文件。

YouTube API 设置

1. 前往 Google Cloud Console。
2. 创建一个新项目，或选择一个现有项目。
3. 在导航菜单中，前往“API 和服务” > “库”。
4. 搜索“YouTube Data API v3”，并为你的项目启用它。
5. 前往“API 和服务” > “凭据”。
6. 点击“+ CREATE CREDENTIALS”，然后选择“API key”。
7. 复制生成的 API 密钥。这就是你的 YOUTUBE_API_KEY。
8. 重要安全步骤： 限制 API 密钥，防止未经授权的使用。点击 API 密钥名称，在“API restrictions”下选择“Restrict key”，然后选择“YouTube Data API v3”。你也可以根据需要添加“Application restrictions”（例如 IP 地址限制）。

系统要求

• Node.js：>=22.0.0（package.json 中指定）
• npm（用于管理依赖和运行脚本）

深入了解：findConsistentOutlierChannels 工具

findConsistentOutlierChannels 工具旨在识别特定细分领域中表现持续超越自身规模的新兴或成熟 YouTube 频道。该工具特别适合寻找高潜力频道的内容创作者、营销人员和分析师。

重要提示：此工具需要连接 MongoDB，以存储和分析频道数据。如果未配置 MDB_MCP_CONNECTION_STRING，则无法使用此工具。

内部逻辑概览

该工具通过多阶段分析流程运行，同时利用 YouTube Data API 和 MongoDB 数据库：

1. 候选项搜索（阶段 1）：

   • 使用提供的 query 在 YouTube 上搜索相关视频和频道。
   • 如果指定了 videoCategoryId 和 regionCode，则根据这两项筛选初始结果。
   • 收集大量潜在频道，以便进行深入分析。

2. 频道筛选（阶段 2）：

   • 获取候选频道的详细统计数据（订阅人数、总观看次数、视频数量）。
   • 根据 channelAge 筛选频道（例如，'NEW' 表示频道创建时间不足 6 个月，'ESTABLISHED' 表示频道创建时间为 6 至 24 个月）。
   • 确保频道达到最低视频数量要求，才能纳入一致性分析。

3. 深入分析（阶段 3）：

   • 获取每个筛选后频道近期表现最佳的视频。
   • 计算每个视频的“病毒式传播因子”（例如，观看次数与订阅人数的比值）。
   • 评估 consistencyLevel（例如，约 30% 的视频表现突出时为 'MODERATE'，约 50% 时为 'HIGH'）。
   • 确定 outlierMagnitude（例如，观看次数超过订阅人数时为 'STANDARD'，观看次数超过订阅人数 3 倍时为 'STRONG'）。

4. 排序与格式化（阶段 4）：

   • 根据频道的一致性、异常表现幅度以及其在细分领域中的整体表现进行排序。
   • 将结果整理为适合大模型的 Token 优化结构，其中包含关键频道指标和表现突出的视频示例。

控制流程的关键参数

此工具的行为主要由以下参数控制：

• query（字符串，必填）：要分析的核心主题或细分领域（例如，“DIY home repair”“quantum computing explained”）。
• channelAge（枚举值："NEW"、"ESTABLISHED"，默认值："NEW"）：将搜索重点放在新兴或较成熟的频道上。
• consistencyLevel（枚举值："MODERATE"、"HIGH"，默认值："MODERATE"）：设定频道视频必须达到何种持续表现水平，才能被视为表现突出。
• outlierMagnitude（枚举值："STANDARD"、"STRONG"，默认值："STANDARD"）：定义视频表现必须超出典型预期多少（例如，观看次数与订阅人数的对比），才能被视为“异常值”。
• videoCategoryId（字符串，可选）：将搜索范围限定在特定的 YouTube 类别 ID。
• regionCode（字符串，可选）：定位与特定地理区域相关的频道。
• maxResults（数字，默认值：10）：限制返回的表现突出的频道数量。

安全注意事项

• API 密钥安全：YOUTUBE_API_KEY 属于敏感信息。切勿将其直接提交到代码库中。请使用环境变量（例如，通过 .env 文件配置，并将该文件列入 .gitignore）。
• **API 配额：**YouTube Data API 有每日使用配额（默认值为 10,000 个单位）。每次调用工具都会扣减配额。请在 Google Cloud Console 中监控用量，并留意每种工具的调用成本。有关各 API 方法成本的详细说明，请参阅官方文档。
• **输入验证：**服务器使用 Zod 对所有工具参数进行严格的输入验证，以增强安全性和可靠性。

许可证

本项目采用 MIT 许可证授权。详情请参阅 LICENSE 文件。