Youtube Ultimate Toolkit MCP

🚀 YouTube终极工具包 - 模型上下文协议（MCP）服务器

这是一个强大的模型上下文协议（MCP）服务器，它能让Claude AI全面访问YouTube的内容，包括视频文字记录、元数据、评论、截图和音频片段。该服务器同时支持Claude桌面版（本地）和Claude网页版（通过OAuth远程访问）。

🚀 快速开始

选项1：本地模式（Claude桌面版）

# 安装
git clone https://github.com/Comzee/Youtube-Ultimate-Toolkit-MCP.git
cd Youtube-Ultimate-Toolkit-MCP
npm install
npm run build

# 运行
node dist/index.js

将以下配置添加到Claude桌面版的配置文件中（Linux系统路径为 ~/.config/claude/claude_desktop_config.json，macOS系统路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "youtube": {
      "command": "node",
      "args": ["/path/to/Youtube-Ultimate-Toolkit-MCP/dist/index.js"]
    }
  }
}

选项2：远程模式（Claude网页版）

远程模式需要进行OAuth设置和一个公共URL。具体设置步骤请参考下面的 远程模式设置。

✨ 主要特性

与其他MCP的对比

工具特性

📦 安装指南

前提条件

• Node.js 18+
• yt-dlp - YouTube内容获取工具（必须保持更新）
• ffmpeg - 用于截图和音频提取（可选）
• YouTube API密钥 - 仅用于评论功能（可选）

安装前提条件

Ubuntu/Debian系统

# Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# yt-dlp（保持更新 - YouTube经常使旧版本失效）
pip3 install --upgrade yt-dlp

# ffmpeg（用于截图和音频）
sudo apt install ffmpeg

macOS系统

brew install node yt-dlp ffmpeg

Windows系统

# 从https://nodejs.org安装Node.js
# 安装yt-dlp: pip install yt-dlp
# 从https://ffmpeg.org/download.html安装ffmpeg

保持yt-dlp更新

YouTube经常更改其API。如果文字记录功能失效，请更新yt-dlp：

pip3 install --upgrade yt-dlp
# 或者在抱怨外部管理包的系统上：
pip3 install --upgrade --break-system-packages yt-dlp

安装步骤

git clone https://github.com/Comzee/Youtube-Ultimate-Toolkit-MCP.git
cd Youtube-Ultimate-Toolkit-MCP
npm install
npm run build

💻 使用示例

get_video

# 获取视频元数据和英文文字记录，包含时间戳
node dist/index.js get_video --url https://www.youtube.com/watch?v=dQw4w9WgXcQ --includeTimestamps true

get_playlist

# 列出播放列表中的视频，最多返回20个
node dist/index.js get_playlist --url https://www.youtube.com/playlist?list=PL1234567890 --limit 20

get_comments

# 获取视频的热门评论，最多返回50条
node dist/index.js get_comments --url https://www.youtube.com/watch?v=dQw4w9WgXcQ --maxResults 50

get_screenshot

# 在视频的第30秒捕获截图
node dist/index.js get_screenshot --url https://www.youtube.com/watch?v=dQw4w9WgXcQ --timestamp 30

get_audio

# 提取视频从第10秒到第60秒的音频片段
node dist/index.js get_audio --url https://www.youtube.com/watch?v=dQw4w9WgXcQ --startTime 10 --endTime 60

📚 详细文档

远程模式设置

远程模式允许你通过HTTPS和OAuth认证将此MCP与Claude网页版（claude.ai）一起使用。

1. 配置环境

cp .env.example .env

编辑 .env 文件：

# OAuth凭证
OAUTH_CLIENT_ID=youtube-mcp-client
OAUTH_CLIENT_SECRET=your-secret-here  # 生成方式: openssl rand -hex 32

# 同意页面的密码（bcrypt哈希）
# 生成方式: node -e "require('bcrypt').hash('your-password', 12).then(console.log)"
AUTH_PASSWORD_HASH=$2b$12$...your-hash-here...

# 可选: 用于get_comments工具的YouTube API密钥
YOUTUBE_API_KEY=your-api-key-here

2. 启动服务器

# 开发环境
npm run start:remote

# 生产环境（使用systemd）
sudo cp youtube-mcp.service /etc/systemd/system/
# 编辑服务文件以设置你的用户名和路径
sudo nano /etc/systemd/system/youtube-mcp.service
sudo systemctl daemon-reload
sudo systemctl enable youtube-mcp
sudo systemctl start youtube-mcp

3. 设置HTTPS（必需）

Claude网页版需要HTTPS。使用nginx作为反向代理：

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://localhost:3010;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 对于长时间运行的请求很重要
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        proxy_set_header X-Accel-Buffering no;
    }
}

4. 连接Claude网页版

1. 转到 设置 → 连接器 → 添加自定义连接器
2. 输入URL: https://your-domain.com/mcp
3. 开始新聊天并启用MCP
4. 让Claude获取YouTube视频 - 授权弹出窗口将出现
5. 在同意页面输入你的密码并点击 "授权"

工具参考

get_video

获取视频元数据和英文文字记录。 参数：

支持的URL格式：

• youtube.com/watch?v=VIDEO_ID
• youtu.be/VIDEO_ID
• youtube.com/shorts/VIDEO_ID
• youtube.com/live/VIDEO_ID
• youtube.com/embed/VIDEO_ID
• m.youtube.com/watch?v=VIDEO_ID
• music.youtube.com/watch?v=VIDEO_ID
• 直接的视频ID: dQw4w9WgXcQ

get_playlist

列出YouTube播放列表中的视频。 参数：

get_comments

获取视频的热门评论。需要在 .env 文件中设置 YOUTUBE_API_KEY。 参数：

get_screenshot

捕获视频的一帧。需要安装ffmpeg。 参数：

返回值： Base64编码的JPEG图像

get_audio

提取音频片段用于分析。需要安装ffmpeg。 参数：

返回值： Base64编码的MP3音频（128kbps）

OAuth与安全

远程模式实现了带有PKCE的OAuth 2.1进行安全认证。

工作原理

1. Claude连接到 /mcp - 发现/握手方法无需认证即可工作
2. 当你使用工具时，Claude会收到一个带有OAuth发现信息的401响应
3. Claude执行动态客户端注册
4. 浏览器打开同意页面 - 你输入密码
5. Claude用授权码交换访问令牌
6. 后续请求使用Bearer令牌

安全特性

故障排除

"No English transcript available"

更新yt-dlp - YouTube经常更改：

pip3 install --upgrade yt-dlp

MCP无法从Claude网页版连接

• 确保HTTPS配置正确
• 检查服务状态: sudo systemctl status youtube-mcp
• 检查日志: sudo journalctl -u youtube-mcp -f

OAuth流程未启动

• 验证 .well-known/ 端点返回200（而不是401）
• 检查浏览器控制台是否有CORS错误
• 确保 /register 返回有效凭证

授权窗口未出现

• OAuth在首次 使用工具 时触发，而不是在连接时
• 开始聊天，启用MCP，然后让Claude获取YouTube视频

Claude使用错误/旧工具

在Claude设置中断开并重新连接MCP以刷新工具列表。

Claude项目提示

在Claude项目中使用此提示以自动利用MCP：

You have access to the YouTube MCP server. When I share a YouTube URL:
1. Automatically fetch the transcript with get_video
2. Provide a summary, key takeaways, and notable quotes
3. For long videos (10+ min), consider using keySegmentsOnly=true first

Available tools:
- get_video: Transcript and metadata (supports timestamps, time ranges, search)
- get_playlist: List videos in a playlist
- get_comments: Top comments (requires API key)
- get_screenshot: Capture frames at any timestamp
- get_audio: Extract audio clips for analysis (max 120s)

架构

• 传输协议： 可流式传输的HTTP（MCP规范2025 - 03 - 26）
• 会话管理： 有状态，使用UUID标识符（内存中）
• OAuth： 授权码 + PKCE，动态客户端注册
• 令牌管理： 内存存储（重启后丢失）

🔧 技术细节

传输协议

采用可流式传输的HTTP协议（MCP规范2025 - 03 - 26），确保数据的高效传输和处理。

会话管理

使用有状态的会话管理，通过UUID标识符在内存中存储会话信息，方便对不同会话进行跟踪和管理。

OAuth认证

实现了带有PKCE的OAuth 2.1认证机制，包括授权码模式和动态客户端注册，保障用户数据的安全和授权过程的可靠性。

令牌存储

令牌采用内存存储方式，但在服务器重启后会丢失，需要重新进行授权。

📄 许可证

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

贡献说明

欢迎贡献代码！请在GitHub上提交问题或拉取请求。