Youtube MCP Server

🚀 YouTube MCP 服务器

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

🚀 快速开始

本服务器借助 YouTube 数据 API v3 提供实时数据访问，让 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")

高级用法

自定义项目集成

对于自定义应用程序或其他 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"

📚 详细文档

函数参考

特殊功能：智能内容评估

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

技术新鲜度评分

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

质量指标

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

智能推荐

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

API 配额使用

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

错误处理

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

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

测试

运行全面的测试套件：

python test_server.py

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

安全注意事项

• 切勿提交你的 credentials.yml 文件。
• 限制你的 API 密钥仅用于 YouTube 数据 API v3。
• 监控配额使用情况，防止意外成本。
• 在生产环境中使用环境变量。

贡献指南

1. 分叉仓库。
2. 创建功能分支 (git checkout -b feature/amazing-feature)。
3. 使用 python test_server.py 测试你的更改。
4. 提交更改 (git commit -m 'Add amazing feature')。
5. 推送到分支 (git push origin feature/amazing-feature)。
6. 打开拉取请求。

开发说明

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

• 增量开发方法 - 一次开发一个函数。
• 测试驱动开发 - 在集成前对每个函数进行测试。
• 用户协作 - 持续反馈和审批机制。
• 备份协议 - 安全开发，具备回滚能力。

详细的开发和测试流程请参阅 documents/testing.md。

故障排除

常见问题

“未找到 API 密钥”错误：

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

“配额超出”错误：

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

“未找到视频”错误：

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

MCP 连接问题：

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

📄 许可证

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

🙏 致谢

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

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