Youtube MCP Server

🚀 YouTube MCP 服务器

这是一个全面的模型上下文协议（MCP）服务器，可通过 YouTube 数据 API v3 提供实时的 YouTube 数据访问。该服务器使 AI 助手能够搜索、分析并检索有关 YouTube 视频、频道、播放列表等的详细信息。

🚀 快速开始

本服务器为 AI 助手提供了便捷的途径来访问和处理 YouTube 上的丰富数据。你可以按照以下步骤进行安装和配置，以开启使用之旅。

✨ 主要特性

14 项完整功能

1. get_video_details - 获取全面的视频信息，包括标题、描述、统计数据和元数据。
2. get_playlist_details - 检索播放列表信息和元数据。
3. get_playlist_items - 列出播放列表中的视频并附带详细信息。
4. get_channel_details - 获取频道信息，包括订阅者数量、视频数量和描述。
5. get_video_categories - 列出特定地区可用的视频类别。
6. get_channel_videos - 获取 YouTube 频道的近期视频。
7. search_videos - 使用可自定义的参数在 YouTube 上搜索视频。
8. get_trending_videos - 检索特定地区的热门视频。
9. get_video_comments - 获取视频的评论，并支持排序选项。
10. analyze_video_engagement - 分析参与度指标并提供洞察。
11. get_channel_playlists - 列出 YouTube 频道的播放列表。
12. get_video_caption_info - 获取可用的字幕/转录信息。
13. evaluate_video_for_knowledge_base - 进行智能内容评估，并为知识库管理提供技术新鲜度评分。
14. get_video_transcript - 从 YouTube 视频中提取实际的转录内容。

关键能力

• ✅ 来自 YouTube 数据 API v3 的实时数据。
• ✅ 全面的错误处理和 API 配额管理。
• ✅ 支持多种 URL 格式（youtube.com、youtu.be、@用户名、频道 ID）。
• ✅ 具备技术新鲜度评分的智能内容评估。
• ✅ 灵活的搜索和过滤选项。
• ✅ 结合行业基准的参与度分析。
• ✅ 支持特定地区的热门内容和类别。
• ✅ 符合 MCP 协议，便于与 AI 无缝集成。

📦 安装指南

第 1 步：克隆仓库

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

第 2 步：安装依赖

pip install -r requirements.txt

第 3 步：获取 YouTube API 密钥

1. 访问 Google 云控制台。
2. 创建一个新项目或选择一个现有项目。
3. 启用 YouTube 数据 API v3。
4. 创建凭证（API 密钥）。
5. （可选）为了安全起见，将 API 密钥限制为仅用于 YouTube 数据 API v3。

第 4 步：配置 API 密钥

在项目根目录下创建一个 credentials.yml 文件：

youtube_api_key: "YOUR_YOUTUBE_API_KEY_HERE"

重要提示：切勿将 credentials.yml 文件提交到版本控制系统！

第 5 步：测试服务器

python test_server.py

这将对所有 14 个功能进行全面测试，以确保一切正常工作。

💻 使用示例

基础用法

基本视频信息

# 获取详细的视频信息
result = await get_video_details("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# 也支持使用视频 ID
result = await get_video_details("dQw4w9WgXcQ")

搜索与发现

# 搜索近期的 Python 教程
tutorials = await search_videos(
    query="Python tutorial",
    max_results=10,
    order="date"
)

# 获取美国的热门视频
trending = await get_trending_videos(region_code="US", max_results=5)

频道分析

# 获取频道信息
channel_info = await get_channel_details("@3Blue1Brown")

# 获取频道的近期视频
recent_videos = await get_channel_videos("@3Blue1Brown", max_results=5)

# 获取频道的所有播放列表
playlists = await get_channel_playlists("@3Blue1Brown")

高级用法

内容评估（特色功能）

# 评估视频是否值得添加到知识库
# 包括针对教育内容的技术新鲜度评分
evaluation = await evaluate_video_for_knowledge_base("Z6nkEZyS9nA")

# 示例输出：
# 🟢 强烈推荐 - 有价值内容的有力指标
# ⏰ 内容新鲜度：非常新（2 天前）
# 🚀 技术时效性：React 2025 内容 - 框架发展迅速

转录提取（新增功能）

# 从视频中提取完整的转录内容
transcript = await get_video_transcript("Z6nkEZyS9nA")

# 也支持使用 URL 和不同语言
transcript_spanish = await get_video_transcript(
    "https://www.youtube.com/watch?v=Z6nkEZyS9nA", 
    language="es"
)

# 示例输出：
# 📝 完整转录：[完整的视频转录文本]
# ⏰ 带时间戳的片段：[00:15] 欢迎来到本教程...
# 单词计数：约 2847 个单词

参与度分析

# 分析视频的参与度指标
engagement = await analyze_video_engagement("dQw4w9WgXcQ")

# 获取视频的评论
comments = await get_video_comments("dQw4w9WgXcQ", max_results=10, order="relevance")

📚 详细文档

功能参考

特殊功能：智能内容评估

evaluate_video_for_knowledge_base 函数包含高级的内容评估：

技术新鲜度评分

• 高波动性主题（React、AWS、AI/ML）：强烈倾向于近期内容。
• 中波动性主题（Python、通用编程）：适度的新鲜度加分。
• 稳定主题（算法、数学）：最小的时效性惩罚。

质量指标

• 观看次数和参与度指标。
• 手动或自动生成的字幕。
• 内容类型检测（教程、评测等）。
• 时长适宜性。
• 技术时效性指标（2024、2025、“最新”、版本号）。

智能推荐

• 🟢 强烈推荐 - 高质量 + 近期技术内容。
• 🟡 适度推荐 - 有一些积极指标。
• 🔴 有限推荐 - 质量指标较少。

API 配额使用

每日限制：10000 单位（默认）。 监控使用情况，以避免配额耗尽。

集成指南

Claude Desktop 集成

1. 安装服务器：按照上述安装步骤进行操作。
2. 添加到 Claude Desktop 配置：编辑你的 Claude Desktop 配置文件：
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Mac：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "youtube": {
      "command": "python",
      "args": ["/path/to/youtube-mcp-server/youtube_mcp_server.py"],
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key_here"
      }
    }
  }
}

3. 重启 Claude Desktop。
4. 验证集成：向 Claude 提问：“你能在 YouTube 上搜索 Python 教程吗？”

Cursor 集成

1. 安装服务器：按照上述安装步骤进行操作。
2. 在 Cursor 设置中配置：
   • 打开 Cursor 设置。
   • 导航到 MCP 服务器。
   • 使用 Python 命令和参数添加新服务器。
3. 设置 API 密钥的环境变量。
4. 使用 Cursor 进行测试：让它搜索 YouTube 内容。

自定义项目集成

对于自定义应用程序或其他 MCP 客户端：

from youtube_mcp_server import (
    get_video_details,
    search_videos,
    evaluate_video_for_knowledge_base
)

# 示例用法
async def example():
    # 搜索视频
    results = await search_videos("machine learning", max_results=5)
    print(results)

    # 评估视频是否适合知识库
    evaluation = await evaluate_video_for_knowledge_base("dQw4w9WgXcQ")
    print(evaluation)

环境变量设置

你也可以使用环境变量代替凭证文件：

export YOUTUBE_API_KEY="your_api_key_here"

🔧 技术细节

错误处理

服务器包含全面的错误处理，以应对以下情况：

• 无效的 API 密钥。
• 配额超出错误。
• 网络连接问题。
• 无效的视频/频道 ID。
• 地区限制。
• 评论/字幕禁用。

测试

运行全面的测试套件：

python test_server.py

这将使用真实的 YouTube 内容对所有 14 个功能进行测试，并提供详细的输出。

开发说明

本项目采用以下方式进行开发：

• 增量方法 - 一次开发一个功能。
• 测试驱动开发 - 在集成之前对每个功能进行测试。
• 用户协作 - 持续反馈和审批环节。
• 备份协议 - 安全开发，具备回滚能力。 详细的开发和测试流程请参阅 documents/testing.md。

故障排除

常见问题

“未找到 API 密钥”错误：

• 确保 credentials.yml 文件存在且格式正确。
• 检查文件权限。
• 验证 API 密钥有效且未受限。

“配额超出”错误：

• 检查你的 Google 云控制台配额使用情况。
• 考虑升级配额或优化请求。
• 对频繁访问的数据使用缓存。

“未找到视频”错误：

• 验证视频 ID 或 URL 是否正确。
• 检查视频是否为私有或受限。
• 确保视频未被删除。

MCP 连接问题：

• 验证配置中的 Python 路径。
• 检查所有依赖项是否已安装。
• 配置更改后重启 MCP 客户端。

📄 许可证

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

🙏 致谢

• 基于 模型上下文协议 构建。
• 由 YouTube 数据 API v3 提供支持。
• 使用 FastMCP 进行开发。

准备好为你的 AI 助手赋予 YouTube 功能了吗？立即开始吧！ 🚀