JinDaGe - youtube-ultimate-toolkit-mcp MCP Details

article

README

🚀 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的对比

| 特性 | 本MCP | 其他多数MCP | |---------|:--------:|:-----------:| | 文字记录 | ✅ | ✅ | | 时间戳 | ✅ | 部分支持 | | 时间范围过滤 | ✅ | 极少支持 | | 文字记录搜索 | ✅ | 极少支持 | | 关键片段（开头/结尾） | ✅ | ❌ | | 元数据 | ✅ | ✅ | | 播放列表 | ✅ | 部分支持 | | 评论 | ✅ | 极少支持 | | 截图 | ✅ | 仅1 - 2个支持 | | 音频片段 | ✅ | ❌ | | 所有URL格式 | ✅ | 部分支持 | | OAuth 2.1 + PKCE | ✅ | ❌ | | 密码保护 | ✅ | ❌ | | 速率限制 | ✅ | ❌ | | Claude网页版支持 | ✅ | 极少支持 |

工具特性

| 工具 | 描述 | |------|-------------| | get_video | 获取视频元数据和文字记录，支持搜索、时间戳和时间范围 | | get_playlist | 列出播放列表中的所有视频 | | get_comments | 获取带有点赞和回复数量的热门评论 | | get_screenshot | 在任意时间戳捕获视频帧 | | get_audio | 提取音频片段（最长120秒）用于语音/音乐分析 |

📦 安装指南

前提条件

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网页版

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

工具参考

`get_video`

获取视频元数据和英文文字记录。 参数： | 参数 | 是否必需 | 描述 | |-----------|----------|-------------| | url | 是 | YouTube URL（任何格式）或视频ID | | includeTimestamps | 否 | 为每行添加 [M:SS] 时间戳 | | startTime | 否 | 文字记录范围的开始时间（例如，"60", "1:00"） | | endTime | 否 | 文字记录范围的结束时间 | | searchTerm | 否 | 搜索文字记录并突出显示匹配项 | | keySegmentsOnly | 否 | 仅返回开头（前40秒）和结尾（后30秒） |

支持的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播放列表中的视频。 参数： | 参数 | 是否必需 | 描述 | |-----------|----------|-------------| | url | 是 | YouTube播放列表URL | | limit | 否 | 最多返回的视频数量（默认: 50，最大: 200） |

`get_comments`

获取视频的热门评论。需要在 .env 文件中设置 YOUTUBE_API_KEY。 参数： | 参数 | 是否必需 | 描述 | |-----------|----------|-------------| | url | 是 | YouTube视频URL或ID | | maxResults | 否 | 评论数量（默认: 25，最大: 100） | | order | 否 | 排序方式: "relevance"（默认）或 "time" |

`get_screenshot`

捕获视频的一帧。需要安装ffmpeg。 参数： | 参数 | 是否必需 | 描述 | |-----------|----------|-------------| | url | 是 | YouTube视频URL | | timestamp | 否 | 捕获时间（默认: "0"）。格式: "30", "1:30", "1:30:00" |

返回值： Base64编码的JPEG图像

`get_audio`

提取音频片段用于分析。需要安装ffmpeg。 参数： | 参数 | 是否必需 | 描述 | |-----------|----------|-------------| | url | 是 | YouTube视频URL | | startTime | 否 | 开始时间（默认: "0"） | | endTime | 否 | 结束时间（可选） | | maxDuration | 否 | 最大时长（默认: 60，最大: 120） |

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

OAuth与安全

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

工作原理

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

安全特性

| 特性 | 保护作用 | |---------|------------| | 密码保护的同意页面 | 只有你可以授权访问 | | Bcrypt密码哈希 | 密码安全存储 | | 速率限制 | 每个IP 5次尝试，然后锁定10分钟 | | XSS保护 | 所有OAuth参数进行HTML转义 | | 命令注入保护 | 使用 shell: false 启动yt-dlp | | PKCE (S256) | 防止授权码拦截 |

故障排除

"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上提交问题或拉取请求。

youtube-ultimate-toolkit-mcp

README

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

🚀 快速开始

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

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

✨ 主要特性

与其他MCP的对比

工具特性

📦 安装指南

前提条件

安装前提条件

Ubuntu/Debian系统

macOS系统

Windows系统

保持yt-dlp更新

安装步骤

💻 使用示例

get_video

get_playlist

get_comments

get_screenshot

get_audio

📚 详细文档

远程模式设置

1. 配置环境

2. 启动服务器

3. 设置HTTPS（必需）

4. 连接Claude网页版

工具参考

get_video

get_playlist

get_comments

get_screenshot

get_audio

OAuth与安全

工作原理

安全特性

故障排除

"No English transcript available"

MCP无法从Claude网页版连接

OAuth流程未启动

授权窗口未出现

Claude使用错误/旧工具

Claude项目提示

架构

🔧 技术细节

传输协议

会话管理

OAuth认证

令牌存储

📄 许可证

贡献说明

Runtime guide

Hosted runtime

Local runtime / other methods

`get_video`

`get_playlist`

`get_comments`

`get_screenshot`

`get_audio`

`get_video`

`get_playlist`

`get_comments`

`get_screenshot`

`get_audio`