yt-dlp-mcp

🎬 yt-dlp-mcp

✨ 機能

🚀 インストール

前提条件

お使いのシステムに yt-dlp をインストールしてください。

はじめに

MCP クライアントに次の設定を追加してください。

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
    }
  }
}

MCP クライアントの設定

claude mcp add yt-dlp npx @kevinwatt/yt-dlp-mcp@latest

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"yt-dlp","command":"npx","args":["-y","@kevinwatt/yt-dlp-mcp@latest"]}'

手動インストール

npm install -g @kevinwatt/yt-dlp-mcp

🛠️ 利用可能なツール

他の MCP サーバーとの名前の競合を避けるため、すべてのツールには ytdlp_ が接頭辞として付いています。

🔍 検索と検出

📝 字幕とトランスクリプト

🎥 動画と音声のダウンロード

💬 コメント

💡 使用例

動画を検索

"Search for Python programming tutorials"
"Find the top 20 machine learning videos"
"Search for 'react hooks tutorial' and show results 10-20"
"Search for JavaScript courses in JSON format"

メタデータを取得

"Get metadata for https://youtube.com/watch?v=..."
"Show me the title, channel, and view count for this video"
"Extract just the duration and upload date"
"Give me a quick summary of this video's info"

コメントを取得

"Get the top 20 comments for https://youtube.com/watch?v=..."
"Get comments as threaded JSON for this video"
"Extract comments as markdown_tree so the reply branches stay intact"
"Get newest comments with maxDepth 1 and maxRepliesPerThread 0"
"Summarize comments in threaded view"

字幕と文字起こしをダウンロード

"List available subtitles for https://youtube.com/watch?v=..."
"Download English subtitles from this video"
"Get a clean transcript of this video in Spanish"
"Download Chinese (zh-Hant) transcript"

コンテンツをダウンロード

"Download this video in 1080p: https://youtube.com/watch?v=..."
"Download audio from this YouTube video"
"Download this video from 1:30 to 2:45"
"Save this Facebook video to my Downloads"

📖 ドキュメント

• API リファレンス - ツールの詳細なドキュメント
• 設定 - 環境変数と設定項目
• Cookie の設定 - 認証と非公開動画へのアクセス
• エラー処理 - よくあるエラーと解決策
• コントリビューション - コントリビューションの方法

🔧 設定

環境変数

# Downloads directory (default: ~/Downloads)
YTDLP_DOWNLOADS_DIR=/path/to/downloads

# Default resolution (default: 720p)
YTDLP_DEFAULT_RESOLUTION=1080p

# Default subtitle language (default: en)
YTDLP_DEFAULT_SUBTITLE_LANG=en

一覧については、設定ガイドをご覧ください。

Proxy and yt-dlp Config File

すべてのツールは yt-dlp の設定ファイル（~/.config/yt-dlp/config）を読み込むため、そこに設定した --proxy、--cookies などのオプションは自動的に適用されます。これは、サーバープロセスに環境変数を渡せない MCP クライアントが利用できる唯一の方法です。

これらは代替の設定です。必要なものだけを設定してください。

対応するプロキシ方式：http、https、socks4、socks5、socks5h。

YTDLP_IGNORE_CONFIG=1 は、0.9.x の状態にそのまま戻す設定ではありません。検索、メタデータ、コメントのツールは常に設定ファイルを読み込むため、この設定を使うと、それらのツールも設定ファイルを読み込まなくなります。

プロキシを使う場合の MCP 設定：

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
      "env": {
        "YTDLP_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

MCP クライアントからサーバーに環境変数を渡せない場合は、代わりにオプションを ~/.config/yt-dlp/config に記述してください。すべてのツールがこのファイルを読み込みます。

--proxy socks5://127.0.0.1:1080
--cookies /path/to/cookies.txt

注：設定ファイルの内容はダウンロードにも適用されます。出力形式を変更するオプション（-x、--remux-video、--recode-video）を設定すると、ダウンロードツールが生成するファイルも変わります。ツールは yt-dlp が実際に書き込んだファイルを報告するため、報告される名前は正しいままです。出力先を指定するオプション（-o、-P）は効果がありません。ツールは常にコマンドラインで絶対パスの --output を渡し、こちらが優先されるためです。

注：yt-dlp の設定ファイルには、コマンドを実行するオプション（--exec、--postprocessor-args、--ffmpeg-location）を含めることができます。これらは AI アシスタントによって呼び出されたものも含め、ツールの呼び出し時にも実行されます。サーバーに設定ファイルを一切読み込ませたくない場合は、YTDLP_IGNORE_CONFIG=1 を設定してください。

Cookie の設定

非公開動画や年齢制限のあるコンテンツへのアクセス、またはレート制限の回避には、Cookie を設定してください。

⚠️ 重要：Cookie 認証には JavaScript ランタイム（deno）のインストールが必要です。Cookie を使用すると、YouTube は JavaScript によるチャレンジの解決が必要な、認証済み API エンドポイントを使用します。deno がないと、ダウンロードは「n challenge solving failed」エラーで失敗します。

deno のインストール：https://docs.deno.com/runtime/getting_started/installation/

# Extract cookies from browser (recommended)
YTDLP_COOKIES_FROM_BROWSER=chrome

# Or use a cookie file
YTDLP_COOKIES_FILE=/path/to/cookies.txt

Cookie を使う場合の MCP 設定：

{
  "mcpServers": {
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "@kevinwatt/yt-dlp-mcp@latest"],
      "env": {
        "YTDLP_COOKIES_FROM_BROWSER": "chrome"
      }
    }
  }
}

対応ブラウザー：brave、chrome、chromium、edge、firefox、opera、safari、vivaldi、whale

詳しい設定手順については、Cookie の設定ガイドを参照してください。

🏗️ アーキテクチャ

使用技術

• yt-dlp - 動画抽出エンジン
• MCP SDK - Model Context Protocol
• Zod - TypeScript を優先したスキーマ検証
• TypeScript - 型安全性と開発者エクスペリエンス

主な機能

• ✅ 型安全：strict モードの TypeScript を全面的に使用
• ✅ 入力検証：実行時検証に Zod スキーマを使用
• ✅ 文字数制限：コンテキストのオーバーフローを防ぐため、自動的に切り詰めます
• ✅ ツールアノテーション：readOnly、destructive、idempotent のヒント
• ✅ エラーガイダンス：LLM 向けの実行可能なエラーメッセージ
• ✅ モジュール設計：関心事を明確に分離

📊 レスポンス形式

JSON 形式

プログラムによる処理に最適です。

{
  "total": 50,
  "count": 10,
  "offset": 0,
  "videos": [...],
  "has_more": true,
  "next_offset": 10
}

Markdown 形式

人間が読みやすい表示です。

Found 50 videos (showing 10):

1. **Video Title**
   📺 Channel: Creator Name
   ⏱️  Duration: 10:30
   🔗 URL: https://...

コメントの Markdown ツリー

返信の文脈が重要な場合の LLM による分析に便利です。

# AI-Ready Comment Threads

source_title: "Sample Video"
comments_detected: 20
root_threads: 6
reply_comments: 14

## Threads

### Thread 1

- comment_id: "abc123"
  parent_id: "root"
  depth: 0
  reply_count: 2
  text:
    | Root comment text
  - comment_id: "reply456"
    parent_id: "abc123"
    depth: 1
    reply_count: 0
    text:
      | Reply text

コメントの制限

YouTube のコメント抽出では、抽出器のタプル全体をサポートしています。

youtube:comment_sort=<sort>;max_comments=<total>,<parents>,<replies>,<repliesPerThread>,<depth>

例：

• デフォルトの動作：maxComments=20 の場合、max_comments=20,20,20,20,2 になります
• ルートコメントのみ：maxDepth=1、maxRepliesPerThread=0
• 返信数を制限：maxReplies=40、maxRepliesPerThread=5、maxDepth=2

🔒 プライバシーとセキュリティ

• トラッキングなし：直接ダウンロードを使用し、分析データを収集しません
• 入力の検証：Zod スキーマによってインジェクションを防止します
• URL の検証：URL の形式を厳密にチェックします
• 文字数制限：コンテキストのオーバーフロー攻撃を防止します
• デフォルトで読み取り専用：ほとんどのツールはシステムの状態を変更しません

🤝 コントリビューション

コントリビューションを歓迎します！コントリビューションガイドをご確認ください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

📝 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については、LICENSEファイルをご覧ください。

🙏 謝辞

• yt-dlp - 優れた動画抽出ツール
• Anthropic - Model Context Protocol の提供
• Dive - MCP 対応 AI プラットフォーム

📚 関連プロジェクト

• MCP Servers - 公式 MCP サーバーの実装
• yt-dlp - コマンドライン動画ダウンローダー
• Dive Desktop - AI エージェントプラットフォーム