YouTube MCP サーバー

YouTube 動画から教育コンテンツ（文字起こしと視覚的に意味のあるフレーム）を抽出し、Claude や ChatGPT など、あらゆる MCP 対応クライアントで利用できるようにする Python ベースの Model Context Protocol (MCP) サーバー。

できること

AI アシスタントに YouTube の URL を渡すだけで、以下のことが可能です：

1. 文字起こしを読む — タイムスタンプ付きの完全なキャプションを取得し、要約・Q&A・コンテンツ分析に利用できます。

2. 動画を見る — 5 段階のコンピュータビジョンパイプラインで最も情報量の多いフレームを抽出し、品質スコアリング、重複除去を行い、AI が「視覚的に確認」できる base64 エンコード済み JPEG として返します。

手動でのダウンロードやコピー＆ペーストは不要。URL を貼り付けて質問するだけです。

ツール

get_transcript

youtube-transcript-api を使用して動画のキャプションを取得します。

パラメータ：

• url (必須) — YouTube 動画の URL

• language (任意、デフォルト: "en") — 優先するキャプション言語

• prefer_manual (任意、デフォルト: true) — 自動生成キャプションよりも手動で作成されたキャプションを優先

戻り値： タイムスタンプ付きのクリーンな文字起こしブロック：

[00:00:00] So I want to start by offering you a free ...
[00:00:15] The key insight here is that ...

get_video_frames

動画全体を分析するパイプラインを実行し、最も意味のある視覚的瞬間を抽出します。

パラメータ：

• url (必須) — YouTube 動画の URL

• max_frames (任意、デフォルト: 20) — 返すフレームの最大数（上限: 40）

• scene_threshold (任意、デフォルト: 0.25) — FFmpeg のシーン検出感度

• output_width (任意、デフォルト: 640) — 返す JPEG の幅（高さは比率に応じて調整）

• min_importance_score (任意、デフォルト: 0.35) — 複合品質スコアの最小値

戻り値：

• メタデータ: video_id、duration_seconds、pipeline_stats、fallback_used

• フレームブロック: 各ブロックに timestamp_ms、composite_score、base64 エンコードされた JPEG 画像

• タイムスタンプとスコア付きの全フレームのインデックス

フレームパイプライン（5 段階）

クイックスタート

前提条件

• Python 3.11

• ffmpeg — 動画処理用

• Tesseract OCR — フレーム内のテキスト検出用

macOS:

brew install ffmpeg tesseract

Ubuntu / Linux:

sudo apt-get install ffmpeg tesseract-ocr tesseract-ocr-eng

Windows: ffmpeg と Tesseract をダウンロードし、両方を PATH に追加します。

確認:

ffmpeg -version
tesseract --version

インストール

# Clone the repository
git clone https://github.com/Ayush-Mamgain/youtube-mcp-server.git
cd youtube-mcp-server

# Create a virtual environment
python3 -m venv venv
source venv/bin/activate        # macOS / Linux
# venv\Scripts\activate      # Windows

# Install dependencies
pip install -r requirements.txt

設定

プロジェクトルートに .env ファイルを作成します:

LOG_LEVEL=DEBUG
MCP_HTTP_PORT=8000

省略時は config.py のデフォルト値が使用されます（任意のチューニング）:

サーバーの起動

python server.py

サーバーは http://localhost:8000 で起動します。

Claude.ai への接続（ローカル）

1. サーバーを起動: python server.py

2. Claude.ai → 設定 → 統合 → MCP サーバーを追加 に移動

3. 入力: http://localhost:8000/mcp

クラウド版 Claude からサーバーにアクセスするには、サーバーを公開する必要があります（下記「デプロイ」を参照）。

API エンドポイント

プロジェクト構成

youtube-mcp-server/
├── server.py              # MCP entry point — FastMCP + Starlette HTTP server
├── config.py              # Loads and validates environment variables
├── logger.py              # stderr-only logging
├── url_parser.py          # Validates YouTube URLs and extracts video IDs
├── transcript.py          # Fetches captions via youtube-transcript-api
├── downloader.py          # Phase 1 — video download with yt-dlp
├── frame_extractor.py     # Phase 2 — scene-change frame extraction via ffmpeg
├── scorer.py              # Phase 3 — multi-signal frame scoring (OpenCV + Tesseract)
├── deduplicator.py        # Phase 4 — perceptual-hash deduplication
├── frame_loader.py        # Phase 5 — resize, JPEG encode, base64
├── video_frames.py        # Orchestrates Phases 1–5 with semaphore and cleanup
├── requirements.txt       # Pinned Python dependencies
└── .gitignore             # Excludes .env, venv, caches, test artifacts

開発ワークフロー

このプロジェクトは 9 つの自己完結型ステージ で構築され、各ステージにテストファイルと検証手順があります：

黄金律: 各ステージは次に進む前に検証します。python test_stage{N}.py を実行して確認してください。

デプロイ

Docker サポートは計画中ですが、まだ設定されていません。このセクションはコンテナ化が完了次第更新されます。

現時点では、Python 3.11、ffmpeg、Tesseract がインストールされた任意のマシンでサーバーを直接実行できます。Docker 対応後のおすすめホスティングオプション：

• Railway

• Fly.io

• Render

デプロイ後、Claude.ai の統合 URL を以下に更新します：

https://YOUR-DEPLOYMENT-URL/mcp

設計上の注意点

• ログはすべて stderr のみに出力。 stdout は MCP 通信専用に予約されています。

• スレッドセーフ: get_video_frames パイプラインは threading.Semaphore(1) を使用して、同時ダウンロードによるシステム過負荷を防ぎます。

• 自動クリーンアップ: 動画処理中に作成された一時ファイルは、各実行後に削除されます。

• 厳格な検証: 動画 ID は ^[A-Za-z0-9_-]{11}$ に対して検証されます。プレイリスト専用 URL、チャンネル URL、不正な入力は、明確なエラーメッセージとともに拒否されます。

• グレースフルデグラデーション: すべてのフレームが最小重要度の閾値を下回った場合、パイプラインは上位 5 フレームにフォールバックし、fallback_used: true をフラグとして設定します。

ライセンス

MIT © Ayush Mamgain

謝辞

FastMCP、Starlette、yt-dlp、youtube-transcript-api、OpenCV を使用して構築されています。