youtube-search

YouTube 検索

キーワードで YouTube を検索し、タイトル、URL、チャンネル、再生回数、再生時間、アップロード日などの構造化された動画メタデータを返します。スクレイピングには yt-dlp を使用し、API キーや OAuth は不要です。

前提条件

uv tool install yt-dlp

確認します：

yt-dlp --version

使い方

基本的な検索

yt-dlp "ytsearch10:claude code skills" --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -r '[.title, .url, .channel, .view_count, .duration_string, .upload_date] | @tsv'

• ytsearch10: — YouTube を検索し、10 件の結果を返します（必要に応じて数を調整してください）
• --dump-json — メタデータを JSON として出力します
• --flat-playlist — ダウンロードせず、一覧表示のみ行います
• --no-warnings — エラー以外の出力を抑制します

構造化された JSON 出力

yt-dlp "ytsearch5:claude code mcp servers" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq '{
    title: .title,
    url: .url,
    channel: .channel,
    views: .view_count,
    duration: .duration_string,
    upload_date: .upload_date,
    description: (.description // "" | .[0:200])
  }'

並べ替えを指定した検索

yt-dlp はサーバー側の並べ替えに対応していません。再生回数や日付で並べ替えるには、すべての結果を取得し、クライアント側で並べ替えます：

# Sort by view count (descending)
yt-dlp "ytsearch20:AI agents 2026" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -s 'sort_by(-.view_count) | .[:10][] | {title, url, channel, views: .view_count}'

# Sort by upload date (newest first)
yt-dlp "ytsearch20:claude code tutorial" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -s 'sort_by(-.upload_date) | .[:10][] | {title, url, channel, upload_date}'

検索結果の件数

ytsearch の後の数字で、取得する結果の件数を指定します：

パターン	結果
ytsearch5:query	5 件の結果
ytsearch10:query	10 件の結果（推奨されるデフォルト値）
ytsearch20:query	20 件の結果
ytsearch50:query	50 件の結果（遅く、レート制限に達する場合があります）

推奨： 15～20 件の結果を取得してから、クライアント側でフィルタリングや並べ替えを行い、ユーザーが希望する上位 N 件に絞り込みます。これにより、過剰な件数を取得せずに、意味のある並べ替えに十分なデータを確保できます。

ワークフロー

User provides search query
        |
        v
+---------------------+
|  Step 0: Deps check |
+----------+----------+
           v
+---------------------+
|  Step 1: Search     |
|  (yt-dlp ytsearch)  |
+----------+----------+
           v
+---------------------+
|  Step 2: Parse JSON |
|  (jq formatting)    |
+----------+----------+
           v
+---------------------+
|  Step 3: Present    |
|  results to user    |
+---------------------+

ステップ 1：検索を実行する

yt-dlp "ytsearch${COUNT}:${QUERY}" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null

ステップ 2：解析して整形する

jq を使って関連するフィールドを抽出します。yt-dlp のメタデータオブジェクト全体には多くのフィールドが含まれますが、検索結果に役立つものは次のとおりです：

フィールド	説明
.title	動画のタイトル
.url	YouTube の完全な URL
.channel	チャンネル名
.view_count	総再生回数（整数）
.duration_string	H:MM:SS または MM:SS 形式の再生時間
.upload_date	YYYYMMDD 形式のアップロード日
.description	動画の説明（長い場合があります。短縮してください）
.like_count	高評価数（null の場合があります）
.comment_count	コメント数（null の場合があります）

ステップ 3：結果を提示する

ユーザー向けに Markdown テーブルとして整形します：

yt-dlp "ytsearch10:${QUERY}" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -s 'sort_by(-.view_count) | .[] | "| \(.title[:60]) | \(.channel) | \(.view_count) | \(.duration_string) | \(.upload_date) |"' -r

ヘッダー行を先頭に付けます：

| Title | Channel | Views | Duration | Date |
|-------|---------|-------|----------|------|

高度なパターン

再生時間でフィルタリングする

# Only videos longer than 10 minutes (600 seconds)
yt-dlp "ytsearch20:deep dive AI agents" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -s '[.[] | select(.duration >= 600)] | sort_by(-.view_count) | .[:10][]'

新しさでフィルタリングする

# Only videos from the last 30 days
CUTOFF=$(date -v-30d +%Y%m%d 2>/dev/null || date -d "30 days ago" +%Y%m%d)
yt-dlp "ytsearch20:claude code" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -s --arg cutoff "$CUTOFF" '[.[] | select(.upload_date >= $cutoff)] | sort_by(-.view_count) | .[]'

チャンネルを指定して検索する

# Search within a specific channel
yt-dlp "ytsearch10:skills site:youtube.com/c/ChannelName" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null

または、チャンネル URL を直接使用します：

yt-dlp "https://www.youtube.com/@ChannelName/search?query=skills" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null

URL のみを抽出する（パイプで渡す場合）

# Get just URLs for feeding into other tools (watch, notebooklm)
yt-dlp "ytsearch10:claude code MCP" \
  --dump-json --flat-playlist --no-warnings 2>/dev/null \
  | jq -r '.url'

組み合わせて使う

このスキルが生成する URL とメタデータは、ほかのスキルに渡して利用できます：

• watch：URL を渡すと、文字起こしの概念、タイムスタンプ付きの視覚的な根拠、質問に基づく動画分析に利用できます
• notebooklm：notebooklm source add "URL" で URL をソースとして渡します

パイプラインの例（自動化されていない手動の手順）：

1. /yt-search — 関連する動画を 10 件見つけます
2. ユーザーが動画を確認して選択します
3. 選択した URL を notebooklm source add または watch に渡します

エラー処理

エラー	原因	解決方法
結果が見つからない	検索語が具体的すぎる、またはスペルミスがある	検索語を広げます
JSON が空	YouTube によって yt-dlp がレート制限された	数分待ってから再試行します
yt-dlp: command not found	インストールされていない	uv tool install yt-dlp
結果が一部のみ	一部の動画が地域制限または非公開	通常の動作です。取得結果は可能な範囲でのものです
タイムアウト	ネットワークまたは YouTube の応答が遅い	結果の件数を減らすか、再試行します

制限事項

• サーバー側での並べ替えなし：YouTube の検索結果は関連度順に返されます。再生回数や日付で並べ替えるには、追加の結果を取得してクライアント側で並べ替える必要があります。
• レート制限：過度なスクレイピング（50 件以上の結果の取得や、短時間での検索の繰り返し）により、YouTube のレート制限に触れる場合があります。リクエストの間隔を空けてください。
• メタデータの完全性：一部のフィールド（.like_count、.comment_count）は、特定の動画では null の場合があります。jq フィルターでは必ず null を処理してください。
• 認証なし：公開されている YouTube データのみを使用します。年齢制限付きまたは非公開の動画は結果から除外されます。
• 検索の関連性：最初の並び順は YouTube の検索アルゴリズムによって決まります。結果が正確な期待に沿わない場合があります。