yt-transcript-cascade-mcp
Provides optional L3 cloud GPU fallback for ASR by uploading audio to the user's Google Colab environment, managing the Colab session lifecycle, and cleaning up remote temporary files after transcription.
Fetches YouTube video subtitles and metadata, with fallback to downloading audio for local or cloud ASR transcription and structured Markdown transcript output.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
🎙️ yt-transcript-cascade-mcp
核心目標:如何可靠地取得 YouTube 逐字稿,並自動輸出結構化 Markdown (
.md) 檔,方便後續 AI Agent 直接調用與人類查看。 零瀏覽器 Cookie、免 YouTube 帳號登入——透過 L1 字幕直取 → L2 本機跨硬體離線 ASR → L3 選配雲端 GPU 備援 三層容災降級架構,並附帶結構化錯誤分類、來源追溯(Provenance)與多維度品質報告。
(註:本文件目前先提供**繁體中文版*,待 M1–M4 達發布階段將補齊 English / 简体中文 / 日本語 等多語系版本。)*
🤖 AI Agent 調用與 .md 產出處理流程
本專案以 「AI Agent 一鍵呼叫 → 取得可信 Markdown 逐字稿檔」 為核心工作流,讓後續的摘要、知識庫(Notion / RAG / Obsidian)、剪輯腳本分析等 Agent 都能直接讀取標準化的 .md 檔:
sequenceDiagram
participant U as 使用者 / 下游 AI Agent
participant M as yt-transcript-cascade-mcp
participant E as L1 字幕 / L2 本機 ASR / L3 Colab
participant D as 本機磁碟 (.md + 快取)
U->>M: 呼叫 get_youtube_transcript(url, save_to_path="transcripts/demo.md")
M->>M: 1. 驗證 YouTube URL 與路徑安全 (防穿越)
M->>D: 2. 查核 Source / ASR Cache(命中直接回傳)
M->>E: 3. 依 CascadePolicy 執行 L1 → L2 → (選配) L3
E-->>M: 回傳帶時間戳分段與耗時指標
M->>M: 4. 執行 QualityAnalyzer 產生獨立品質報告
M->>D: 5. 原子寫入結構化 Markdown 檔(含 YAML Frontmatter)
M-->>U: 回傳 server_saved_path + 來源追溯 + 內聯預覽(超過長度上限自動截斷省 Token)產出的 Markdown (.md) 結構範例
預設 output_format="markdown" 會產出人機雙讀的標準 .md 檔(可直接丟給其他 Agent 閱讀或手動檢視):
---
video_id: mIg76INLBMU
title: "影片標題"
channel: "頻道名稱"
source_type: LOCAL_ASR # MANUAL_SUBTITLE | AUTO_SUBTITLE | LOCAL_ASR | CLOUD_ASR
tier_used: L2_LOCAL_ASR
source_language: zh-Hant
quality_status: OK # OK | WARNING
duration_coverage_ratio: 0.985
---
# 影片標題
- [00:00] 第一段逐字稿內容...
- [00:15] 第二段逐字稿內容...雲端授權與上傳前告知
AUTO模式:L1/L2 無須授權;僅於 L2 無法處理且顯式傳入enable_colab_fallback=true時才進入 L3,並於音檔上傳前發出cloud_upload_notice告知。COLAB_ONLY模式:強制要求allow_cloud_processing=true(未授權即回INVALID_INPUT),同樣於音檔上傳前發出cloud_upload_notice。
Related MCP server: youtube-transcript-mcp
📌 功能成熟度總覽 (Capability Status)
本專案嚴格區分「規劃中」與「已實測驗證」,絕不讓文件宣稱領先於程式碼實際驗證程度:
模組 / 能力 | 目標階段 | 當前狀態 | 說明 |
MCP 介面 ( | M1 |
| 同步執行 + 共用 |
L2 本機離線 ASR(NVIDIA CUDA / CPU | M2 |
| 分層能力探測 + |
L2 延伸硬體(Apple Silicon MPS) | M2 |
| 視實機 Capability Probe 結果啟用,異常自動退回 CPU |
雙層快取治理 + 跨程序鎖 + 安全閘門 + Benchmark | M3 |
| 原子寫入、音檔/模型指紋、路徑防穿越與多場景固定音檔基準測試 |
L3 Google Colab GPU 備援(macOS / Linux / WSL2) | M4 |
| 選配 Opt-in,內建 |
L3 Google Colab GPU 備援(Windows 原生) | M4 |
| 上游 |
(註:AMD ROCm 尚未完成實機驗證,暫不列入正式支援矩陣。)
🔄 三層容災降級與 execution_mode 流程
flowchart LR
U["YouTube URL"] --> C{"Source / ASR 快取?"}
C -- "命中" --> R["回傳 TranscriptResult<br/>(Provenance + QualityReport)"]
C -- "未命中" --> L1["L1: yt-dlp 單一語系字幕"]
L1 -- "成功" --> R
L1 -- "不可恢復<br/>(私人/下架/需登入)" --> E["立即終止回傳 ErrorCode"]
L1 -- "可降級<br/>(無字幕/429/字幕403)" --> L2["L2: 下載音檔 + 本機 ASR<br/>(分層硬體與引擎探測)"]
L2 -- "成功" --> R
L2 -- "本機無可用引擎且<br/>enable_colab_fallback=true" --> L3["L3: Colab GPU 備援<br/>(Lifecycle Manager)"]
L3 --> R雲端授權語意分離
AUTO模式:L1 與 L2 無須雲端授權;僅在 L2 無法處理且顯式傳入enable_colab_fallback=true時,才自動降級 L3。COLAB_ONLY模式:跳過 L1/L2,仍於本機下載音檔後上傳 Colab;強制要求顯式傳入allow_cloud_processing=true(未授權即回傳INVALID_INPUT),並於回應中附帶雲端上傳告知。
💻 L2 本機硬體與「引擎 × 後端 × 模型」預設策略
本專案不以單一顯卡型號寫死參數,也不提供未驗證的主觀秒數保證;系統先執行分層能力探測,並於實測階段以 RTF(asr_sec / duration_sec) 搭配四段耗時(下載 / 載入 / 轉錄 / 總耗時)呈現效能基準。
本機硬體與後端條件 | 支援級別 | 預設引擎與推論精度 | 模型策略 |
NVIDIA CUDA(可用 VRAM ≥ 7.5 GB) |
|
| 優先 |
NVIDIA CUDA(6–7.5 GB VRAM) |
|
| 探測 |
NVIDIA CUDA(4–6 GB VRAM) |
|
|
|
無獨顯 / VRAM < 4 GB(純 CPU) |
|
|
|
Apple Silicon ( |
|
| 經探測異常自動退回 CPU |
🔒 資料隱私與網路傳輸邊界
本專案採零瀏覽器 Cookie、免 YouTube 帳號登入設計,各層級網路與檔案邊界完全透明:
L1(字幕直取):僅向 YouTube 公開端點請求字幕與影片中繼資料。
L2(本機離線 ASR):音檔下載與語音辨識完全在本機執行,音檔不離開本機。
L3(選配 Colab 備援,預設關閉):須依模式顯式授權
enable_colab_fallback=true或allow_cloud_processing=true才會啟用;音檔會先於本機下載再暫時上傳至您個人帳號的 Google Colab 環境,完成後立即清除遠端暫存檔並終止由本專案owner_id建立之 Session(絕不誤關外部 Session;若清理達上限仍失敗將保留STOP_FAILED紀錄並明確警示)。
☁️ L3 選配教學:Google Colab GPU 雲端備援(M4 階段)
⚠️ 平台支援說明:上游
google-colab-cli官方支援 macOS 與 Linux(Windows 使用者建議透過 WSL2;Windows 原生環境僅屬EXPERIMENTAL)。
前置條件與資源聲明
Google Colab 算力資格:需具備可用 GPU 算力之 Google 帳號(例如符合地區資格的 Google AI Pro 訂閱或 Colab Pay-As-You-Go / Colab Pro 算力單位 Compute Units)。
動態資源與成本聲明:L3 依帳號權益與雲端當下可用資源動態分配 GPU;不保證固定 GPU 型號或固定 Compute Units 費率。(特定條件參考:2026-11-22 以 Tesla T4 + PyTorch
openai-whisper turbo轉錄 16:32 中文音檔,轉錄約 58 秒、全程約 94 秒、扣減約0.02 CU,僅供參考。)
一次性設定流程(Linux / macOS / WSL2)
安裝官方
google-colab-cli(亦可參考 etrnya/colab-mcp-starter):pip install git+https://github.com/googlecolab/jupyter-kernel-client.git pip install git+https://github.com/googlecolab/google-colab-cli.git執行
colab usage完成官方 OAuth 授權(憑證存於系統安全金鑰環,不入設定檔)。呼叫
get_youtube_transcript時依需求傳入enable_colab_fallback=true(AUTO故障備援)或execution_mode="COLAB_ONLY"+allow_cloud_processing=true(主動雲端執行)。
📚 專案文件導覽
PRD.md — 產品需求規格書 v1.2.2(含完整 14 種 ErrorCode、正式 MCP JSON Schema、39 列需求追溯矩陣與 M0–M4 路線圖)
GLOSSARY.md — 術語字典與變數命名標準 v1.2.2
THIRD_PARTY_NOTICES.md — 上游依賴、模型權重與外部二進位檔授權完整揭露
.agents/AGENTS.md — AI 協作專規與工程紅線 v1.2.2
LICENSE — Apache License 2.0 授權全文
🙏 使用與參考之開源專案來源
本專案核心程式碼採用 Apache License 2.0;上游依賴、模型權重與外部工具依其原始授權條款使用,完整授權揭露請參閱 THIRD_PARTY_NOTICES.md:
📄 授權條款 (License)
Copyright 2026 etrnya
本專案核心程式碼採用 Apache License 2.0 授權發布。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
YouTube transcripts for AI agents: text, JSON, SRT, or VTT in 150+ languages, with AI fallback.
Bulk YouTube transcripts from videos, channels, playlists or search: text, RAG chunks, SRT, VTT.
Clean YouTube transcripts for agents: single videos, channels, playlists, plus AI caption cleanup.
Transcripts from YouTube videos, whole channels and playlists for AI agents, with bulk ZIP export.
Related MCP Servers
- AlicenseBqualityDmaintenanceDownloads YouTube audio and transcribes it locally using faster-whisper, saving transcripts as Markdown and JSON files for Obsidian and Hermes ingestion.4Apache 2.0
- AlicenseAqualityDmaintenanceEnables fetching YouTube video transcripts as Markdown files with chapter indexing, so LLMs can read only relevant sections and save context.2MIT
- AlicenseAqualityCmaintenanceEnables MCP clients and agents to fetch YouTube transcripts and caption lists from video IDs or links, preferring manual/auto captions by ordered language preference and falling back to local Faster-Whisper audio transcription when captions are unavailable. Results include source, language, full text and timestamped segments, with CLI exports to JSON, text, SRT and WebVTT, all without paid APIs or API keys.3MIT
- AlicenseAqualityCmaintenanceEnables transcription of YouTube videos by using available captions or falling back to actual audio with local Whisper ASR and multiple free providers. It supports job status, transcript retrieval and search, audio excerpts, and export formats while keeping source links and timestamps.10MIT