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上提交問題或拉取請求。