星战科技xingzhan.cloud
返回市场
YouTube-MCP服务器增强版

YouTube-MCP服务器增强版

作者：labeveryday5 星标更新：2025-08-25
安装使用来源：spider==github.com

项目介绍

YouTube MCP Server Enhanced 🚀

一个全面的微对话处理器（MCP）服务器，用于通过 yt-dlp 提取和分析 YouTube 数据。

🚀 功能

核心提取

  • 视频信息：元数据、统计数据、互动指标
  • 频道信息：统计信息、订阅者数量、观看次数、验证状态
  • 播放列表详情：视频列表、时长、总观看次数
  • 评论：带回复的线程评论及互动
  • 字幕：自动生成和手动字幕

高级功能

  • YouTube 搜索：搜索视频、频道和播放列表
  • 热门视频：按地区获取热门内容
  • 批量处理：并发从多个 URL 中提取
  • 智能缓存：基于 TTL 的可配置缓存
  • 自动重试：失败请求的指数退避重试
  • 健康监控：实时提取器状态和配置

🛠️ 安装

先决条件

  • Python 3.10+
  • uv 包管理器（必需）
  • yt-dlp（通过 uv 自动安装）

⚠️ 重要提示：此项目需要 uv 才能正常运行。首先安装它：

# 安装 uv（macOS/Linux）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或通过 Homebrew（macOS）
brew install uv

# 或通过 pip
pip install uv

设置

# 克隆仓库
git clone <repository-url>
cd youtube-mcp-server-enhanced

# 安装 yt-dlp 和所有依赖项
uv add yt-dlp
uv sync

# 验证安装
uv run yt-dlp --version

⚙️ 配置

环境变量（.env 文件）

在项目根目录创建一个 .env 文件以配置服务器：

# 复制示例文件
cp .env.example .env

# 使用你喜欢的设置编辑
nano .env

示例 .env 配置：

# 速率限制（例如，“500K”表示每秒 500KB，“1M”表示每秒 1MB）
YOUTUBE_RATE_LIMIT=500K

# 重试配置
YOUTUBE_MAX_RETRIES=5
YOUTUBE_RETRY_DELAY=2.0
YOUTUBE_TIMEOUT=600

# 缓存
YOUTUBE_ENABLE_CACHE=true
YOUTUBE_CACHE_TTL=3600

# 日志级别
LOG_LEVEL=INFO

MCP 客户端配置

Claude Desktop（macOS）

添加到你的 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "youtube-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/youtube-mcp-server-enhanced",
        "python",
        "-m",
        "src.youtube_mcp_server.server"
      ],
      "env": {
        "YOUTUBE_RATE_LIMIT": "500K",
        "YOUTUBE_MAX_RETRIES": "5",
        "YOUTUBE_RETRY_DELAY": "2.0",
        "YOUTUBE_TIMEOUT": "600",
        "YOUTUBE_ENABLE_CACHE": "true",
        "YOUTUBE_CACHE_TTL": "3600"
      }
    }
  }
}

其他 MCP 客户端

对于其他 MCP 客户端，配置服务器命令如下：

uv run --directory /path/to/youtube-mcp-server-enhanced python -m src.youtube_mcp_server.server

默认值

  • 速率限制：无（使用 YouTube 默认值）
  • 最大重试次数：5（从 3 增加以提高可靠性）
  • 重试延迟：2.0 秒（带有指数退避）
  • 超时：600 秒（10 分钟）
  • 缓存 TTL：3600 秒（1 小时）
  • 缓存：默认启用

🎯 可用的 MCP 工具

数据提取

工具描述示例
get_video_info()提取全面的视频元数据get_video_info("https://youtube.com/watch?v=...")
get_channel_info()提取频道信息和统计（支持多种 URL 格式）get_channel_info("https://youtube.com/@channel") 或 get_channel_info("https://youtube.com/ChannelName")
get_playlist_info()提取播放列表详情和视频列表get_playlist_info("https://youtube.com/playlist?list=...")
get_video_comments()提取视频评论和回复get_video_comments("https://youtube.com/watch?v=...", 50)
get_video_transcript()提取视频字幕get_video_transcript("https://youtube.com/watch?v=...")

搜索与发现

工具描述示例
search_youtube()搜索视频、频道或播放列表search_youtube("Python 教程", "video", 20)
get_trending_videos()获取按地区的热门视频get_trending_videos("US", 15)

分析与见解

工具描述示例
analyze_video_engagement()分析互动指标并进行基准比较analyze_video_engagement("https://youtube.com/watch?v=...")
search_transcript()在视频字幕中搜索文本search_transcript("https://youtube.com/watch?v=...", "查询")

批量操作

工具描述示例
batch_extract_urls()并发处理多个 URLbatch_extract_urls(["url1", "url2"], "video")

系统管理

工具描述示例
get_extractor_health()监控提取器健康状况和状态get_extractor_health()
get_extractor_config()查看当前配置get_extractor_config()
clear_extractor_cache()清除所有缓存数据clear_extractor_cache()

MCP 提示

提示描述示例
analyze-video对视频进行全面分析，可选包括评论和字幕analyze-video(url, include_comments=true, include_transcript=true)
compare-videos比较多个视频的互动指标compare-videos([url1, url2, url3])

📊 数据模型

VideoInfo

{
    "metadata": {
        "id": "video_id",
        "title": "视频标题",
        "description": "视频描述...",
        "uploader": "频道名称",
        "uploader_id": "channel_id",
        "upload_date": "20240101",
        "tags": ["标签1", "标签2"],
        "categories": ["娱乐"],
        "thumbnail": "https://..."
    },
    "statistics": {
        "view_count": 1000,
        "like_count": 100,
        "comment_count": 25,
        "duration_seconds": 120,
        "duration_string": "2:00"
    },
    "engagement": {
        "like_to_view_ratio": 0.05,
        "comment_to_view_ratio": 0.025,
        "like_rate_percentage": "5.000%",
        "comment_rate_percentage": "2.500%"
    },
    "technical": {
        "age_limit": 0,
        "availability": "公开",
        "live_status": "非直播"
    }
}

ChannelInfo

{
    "id": "channel_id",
    "name": "频道名称",
    "url": "https://youtube.com/@channel",
    "description": "频道描述...",
    "avatar_url": "https://...",
    "banner_url": "https://...",
    "verified": true,
    "country": "US",
    "language": "en",
    "tags": ["标签1", "标签2"],
    "statistics": {
        "subscriber_count": 10000,
        "video_count": 150,
        "view_count": 500000
    }
}

PlaylistInfo

{
    "id": "playlist_id",
    "title": "播放列表标题",
    "description": "播放列表描述...",
    "uploader": "频道名称",
    "uploader_id": "channel_id",
    "video_count": 25,
    "total_duration_seconds": 7200,
    "total_duration_formatted": "2h 0m",
    "total_views": 50000,
    "videos": [
        {
            "video_id": "video_id",
            "title": "视频标题",
            "uploader": "频道名称",
            "duration": 300,
            "view_count": 2000,
            "playlist_index": 1
        }
    ]
}

🔍 使用示例

基本视频分析

# 获取全面的视频信息
video_info = await get_video_info("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# 提取视频评论
comments = await get_video_comments("https://www.youtube.com/watch?v=dQw4w9WgXcQ", max_comments=50)

# 获取视频字幕
transcript = await get_video_transcript("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# 在字幕中搜索
results = await search_transcript("https://www.youtube.com/watch?v=dQw4w9WgXcQ", "永远不会")

频道和播放列表分析

# 获取频道信息
channel_info = await get_channel_info("https://www.youtube.com/@RickAstleyYT")

# 获取播放列表详情
playlist_info = await get_playlist_info("https://www.youtube.com/playlist?list=...")

搜索与发现

# 搜索视频
results = await search_youtube("Python 编程教程", "video", 10)

# 获取热门视频
trending = await get_trending_videos("US", 20)

高级分析

# 分析视频互动并进行基准比较
engagement = await analyze_video_engagement("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# 比较多个视频
comparison = await compare_videos([
    "https://youtube.com/watch?v=video1",
    "https://youtube.com/watch?v=video2"
])

批量处理

# 并发处理多个 URL
results = await batch_extract_urls([
    "https://youtube.com/watch?v=video1",
    "https://youtube.com/watch?v=video2"
], "video")

⚡ 性能特性

缓存

  • 内存缓存：基于 TTL 的可配置缓存
  • 缓存键：每个请求类型和参数的唯一键
  • 缓存管理：查看统计信息、清除缓存、配置 TTL

重试逻辑

  • 自动重试：可配置的重试尝试次数
  • 指数退避：增加重试之间的延迟
  • 错误处理：失败时优雅降级

批量处理

  • 并发提取：使用 asyncio 同时处理多个 URL
  • 异步操作：非阻塞 I/O 以提高性能
  • 结果聚合：组合结果并提供成功和失败计数

🏥 健康监控

健康状态

health = await get_extractor_health()
# 返回：
{
    "health": {
        "status": "健康",
        "yt_dlp_available": true,
        "yt_dlp_version": "2025.6.30",
        "cache": {"enabled": true, "size": 5, "ttl": 3600},
        "config": {"rate_limit": "1M", "max_retries": 3, "timeout": 300}
    },
    "cache": {
        "enabled": true,
        "size": 5,
        "ttl": 3600,
        "keys": ["key1", "key2"],
        "total_keys": 5
    },
    "server_version": "0.1.0",
    "mcp_version": "1.0.0"
}

配置视图

config = await get_extractor_config()
# 返回当前提取器设置和状态

🚨 错误处理

重试策略

  • 自动重试：默认最多 5 次尝试（可配置）
  • 指数退避：2s、4s、8s 延迟
  • 速率限制：500KB/s 限制，间隔 2 秒睡眠
  • 优雅降级：尽可能返回部分结果

错误类型

  • YouTubeExtractorError：特定于提取的错误
  • InvalidURLError：无效的 YouTube URL 格式
  • RuntimeError：一般执行错误

故障排除

速率限制问题

如果你遇到速率限制问题：

  1. 在 .env 中增加睡眠间隔：YOUTUBE_RETRY_DELAY=3.0
  2. 减少速率限制：YOUTUBE_RATE_LIMIT=300K
  3. 减少并发请求

yt-dlp 不工作

  1. 确保已安装 uv：uv --version
  2. 验证 yt-dlp 安装：uv run yt-dlp --version
  3. 如果直接访问失败，服务器会自动使用 uv run yt-dlp

MCP 连接问题

  1. 在代码更改后重启你的 MCP 客户端
  2. 检查日志中的具体错误消息
  3. 验证环境变量是否正确加载

🔧 开发

运行服务器

⚠️ 始终使用 uv run 以确保正确的依赖管理：

# 启动 MCP 服务器（推荐）
uv run python -m src.youtube_mcp_server.server

# 或如果你有 run_server.py 文件
uv run python run_server.py

测试

# 运行所有测试
uv run pytest tests/

# 运行特定测试文件
uv run pytest tests/test_basic.py

# 运行覆盖率测试
uv run pytest --cov=src tests/

📈 使用案例

内容分析

  • 视频表现：分析观看次数、互动指标
  • 频道增长：跟踪订阅者和观看次数趋势
  • 内容发现：查找热门和受欢迎的内容

研究与分析

  • 市场研究：分析竞争对手频道和内容
  • 趋势分析：识别热门话题和内容类型
  • 观众洞察：了解观众偏好和行为

内容管理

  • 播放列表组织：管理和分析视频集合
  • 评论审核：提取和分析用户反馈
  • 字幕分析：处理和搜索视频内容

🤝 贡献

  1. 分叉仓库
  2. 创建功能分支
  3. 进行更改
  4. 为新功能添加测试
  5. 提交拉取请求

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

🙏 致谢

  • yt-dlp：核心 YouTube 提取引擎
  • FastMCP：MCP 服务器框架
  • Pydantic：数据验证和序列化

📞 支持

🗺️ 发展路线图

  • 批量处理多个视频
  • 缓存层以提高性能
  • 高级分析（互动分析、基准）
  • 速率限制和配额管理
  • 导出功能（JSON、CSV 等）
  • WebSocket 支持实现实时更新
  • 集成示例与流行的 MCP 客户端

由杜安·莱特福特制作 ❤️

通过模型上下文协议（Model Context Protocol），赋能开发者从 YouTube 内容中提取有意义的见解。