You Tube MCP Server Enhanced

YouTube MCP服务器增强🚀

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

🚀 特性

岩心提取

• 视频信息：元数据、统计数据、参与度指标
• 频道信息：统计数据、订阅者计数、查看计数、验证状态
• 播放列表详细信息：视频列表、持续时间、总观看次数
• 评论：附带回复和参与的多线程评论
• 文字记录：自动生成和手动字幕

高性能

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

🛠️ 安装

先决条件

• Python 3.10+
• 紫外线 包管理器 （必填）
• yt-dlp （通过紫外线自动安装）

⚠️ 重要提示：此项目需要 uv 正确运行。先安装：

# Install uv (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via Homebrew (macOS)
brew install uv

# Or via pip
pip install uv

设置

# Clone the repository
git clone 
cd youtube-mcp-server-enhanced

# Install yt-dlp and all dependencies
uv add yt-dlp
uv sync

# Verify installation
uv run yt-dlp --version

⚙️ 配置

环境变量（.env文件）

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

# Copy the example file
cp .env.example .env

# Edit with your preferred settings
nano .env

示例 .env 配置：

# Rate limiting (e.g., "500K" for 500KB/s, "1M" for 1MB/s)
YOUTUBE_RATE_LIMIT=500K

# Retry configuration
YOUTUBE_MAX_RETRIES=5
YOUTUBE_RETRY_DELAY=2.0
YOUTUBE_TIMEOUT=600

# Caching
YOUTUBE_ENABLE_CACHE=true
YOUTUBE_CACHE_TTL=3600

# Logging level
LOG_LEVEL=INFO

MCP客户端配置

克劳德桌面（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工具

数据提取

搜索与发现

分析和见解

批量操作

系统管理

MCP提示

📊 数据模型

视频信息表

{
    "metadata": {
        "id": "video_id",
        "title": "Video Title",
        "description": "Video description...",
        "uploader": "Channel Name",
        "uploader_id": "channel_id",
        "upload_date": "20240101",
        "tags": ["tag1", "tag2"],
        "categories": ["Entertainment"],
        "thumbnail": "https://..."
    },
    "statistics": {
        "view_count": 1000,
        "like_count": 50,
        "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": "public",
        "live_status": "not_live"
    }
}

频道信息

{
    "id": "channel_id",
    "name": "Channel Name",
    "url": "https://youtube.com/@channel",
    "description": "Channel description...",
    "avatar_url": "https://...",
    "banner_url": "https://...",
    "verified": true,
    "country": "US",
    "language": "en",
    "tags": ["tag1", "tag2"],
    "statistics": {
        "subscriber_count": 10000,
        "video_count": 150,
        "view_count": 500000
    }
}

播放列表信息

{
    "id": "playlist_id",
    "title": "Playlist Title",
    "description": "Playlist description...",
    "uploader": "Channel Name",
    "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": "Video Title",
            "uploader": "Channel Name",
            "duration": 300,
            "view_count": 2000,
            "playlist_index": 1
        }
    ]
}

🔍 使用示例

基本视频分析

# Get comprehensive video information
video_info = await get_video_info("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Extract video comments
comments = await get_video_comments("https://www.youtube.com/watch?v=dQw4w9WgXcQ", max_comments=50)

# Get video transcript
transcript = await get_video_transcript("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Search within transcript
results = await search_transcript("https://www.youtube.com/watch?v=dQw4w9WgXcQ", "never gonna")

频道和播放列表分析

# Get channel information
channel_info = await get_channel_info("https://www.youtube.com/@RickAstleyYT")

# Get playlist details
playlist_info = await get_playlist_info("https://www.youtube.com/playlist?list=...")

搜索和发现

# Search for videos
results = await search_youtube("Python programming tutorials", "video", 10)

# Get trending videos
trending = await get_trending_videos("US", 20)

高级分析

# Analyze video engagement with benchmarks
engagement = await analyze_video_engagement("https://www.youtube.com/watch?v=dQw4w9WgXcQ")

# Compare multiple videos
comparison = await compare_videos([
    "https://youtube.com/watch?v=video1",
    "https://youtube.com/watch?v=video2"
])

批处理

# Process multiple URLs concurrently
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()
# Returns:
{
    "health": {
        "status": "healthy",
        "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()
# Returns current extractor settings and status

🚨 错误处理

重试策略

• 自动检索：默认情况下最多5次尝试（可配置）
• 指数退避：2秒、4秒、8秒延迟
• 速率限制：500KB/s限制，睡眠间隔为2秒
• 故障弱化：尽可能返回部分结果

错误类型

• YouTubeExtractor错误：提取特定错误
• 无效URL错误：无效的YouTube URL格式
• 运行时错误：一般执行错误

故障排除

利率限制问题

如果遇到速率限制：

1. 增加睡眠间隔 .env: YOUTUBE_RETRY_DELAY=3.0
2. 利率下限： YOUTUBE_RATE_LIMIT=300K
3. 减少并发请求

yt-dlp不工作

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

MCP连接问题

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

🔧 发展

运行服务器

⚠️ 始终使用 uv run 为了确保适当的依赖关系管理：

# Start the MCP server (recommended)
uv run python -m src.youtube_mcp_server.server

# Or if you have a run_server.py file
uv run python run_server.py

测试

# Run all tests
uv run pytest tests/

# Run specific test file
uv run pytest tests/test_basic.py

# Run with coverage
uv run pytest --cov=src tests/

📈 用例

内容分析

• 视频表演：分析浏览次数、参与度指标
• 渠道增长：跟踪订户并查看计数趋势
• 内容发现：查找趋势和流行内容

研究与分析

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

内容管理

• 播放列表组织：管理和分析视频收藏
• 评论审核：提取和分析用户反馈
• 成绩单分析：处理和搜索视频内容

🤝 贡献

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

📄 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

🙏 致谢

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

📞 支持

• 问题:
• 讨论:
• 电子邮件: info@labeveryday.com

🗺️ Roadmap

• \[x\] 批量处理 多个视频
• \[x\] 缓存层 为了提高性能
• \[x\] 高级分析 （参与度分析、基准）
• \[x\] 速率限制 配额管理
• \[ \] 导出功能 （JSON、CSV等）
• \[ \] WebSocket支持 用于实时更新
• \[ \] 集成示例 与流行的MCP客户端

______________________________________________________________________

由以下材料制成❤️ 作者：杜安·莱特富特

*使开发人员能够通过模型上下文协议从YouTube内容中提取有意义的见解。*