YouTube MCP Server

YouTube MCP Server

ホスト型の Model Context Protocol（MCP）サーバーです。Claude、Cursor、Windsurf、その他すべての MCP クライアントから、読み取り専用の YouTube ツールを 4 つ利用できます。Google Cloud プロジェクトや YouTube Data API キーがなくても、YouTube の検索、動画やチャンネルのデータの取得、字幕の取得ができます。

毎月 1,000 クレジットを無料で利用でき、クレジットカードは不要です。YouTube への呼び出し 100 回分に相当します。

https://mcp.hasdata.com/mcp?apis=youtube

• プロンプトとリソース

目次

• 必要なもの
• クイックスタート
• プロンプトの例
• ツール
• エラーと失敗時の動作
• 料金、無料枠、利用制限
• ツールの選択
• 比較
• FAQ
• HasData のリンク
• 開発
• コントリビューション
• ライセンス

必要なもの

カスタムヘッダーを使ったストリーミング可能な HTTP に対応する MCP クライアントと、無料で作成できる ダッシュボード の HasData API キーが必要です。それ以外は何も必要ありません。これはリモートサーバーなので、URL とヘッダーを設定するだけで利用でき、コンテナーを起動する必要も、Google アカウントを使う必要もありません。stdio のみ対応するクライアントでは、代わりに @hasdata/youtube-mcp（npm）または hasdata-youtube-mcp（PyPI）のランチャーを利用できます。

クイックスタート

サーバー URL はすべてのクライアントで共通です。Claude Code と Claude Desktop では実際に動作させて説明します。ほかのブロックは、それぞれのクライアントがリモートサーバー用にドキュメントで定めている形式に従います。

OAuth に対応したクライアントは、同じ URL をコネクターとして追加してサインインすれば、設定ファイルにキーを入力せずに利用できます。

claude mcp add --transport http youtube "https://mcp.hasdata.com/mcp?apis=youtube" \
  --header "x-api-key: HASDATA_API_KEY"

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@hasdata/youtube-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "youtube": {
      "command": "uvx",
      "args": ["hasdata-youtube-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "youtube": {
      "url": "https://mcp.hasdata.com/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "youtube": {
      "serverUrl": "https://mcp.hasdata.com/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "youtube": {
      "url": "https://mcp.hasdata.com/mcp?apis=youtube",
      "type": "streamableHttp",
      "headers": { "x-api-key": "HASDATA_API_KEY" },
      "disabled": false
    }
  }
}

{
  "servers": {
    "youtube": {
      "type": "http",
      "url": "https://mcp.hasdata.com/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

[mcp_servers.youtube]
url = "https://mcp.hasdata.com/mcp?apis=youtube"

[mcp_servers.youtube.headers]
"x-api-key" = "HASDATA_API_KEY"

{
  "mcpServers": {
    "youtube": {
      "httpUrl": "https://mcp.hasdata.com/mcp?apis=youtube",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

プロンプトの例

コードではなく、プロンプトです。1 つ貼り付けると、エージェントが使うツールを選びます。MCP ではモデルが呼び出し回数を決め、成功した呼び出しごとに 10 クレジットかかるため、それぞれに必要な呼び出し回数を記載しています。

過去 1 か月に公開された、Model Context Protocol に関する再生回数上位 10 本の動画を見つけ、最上位の動画の文字起こしを取得して、ツール呼び出しについて述べている 3 つの主張を教えてください。

2 回の呼び出し、20 クレジット。

チャンネル @GoogleDevelopers を調べてください。公開しているタブを一覧表示し、最近のアップロード 5 件を要約して、繰り返し登場するトピックを教えてください。

2 回の呼び出し、20 クレジット。まだ確認していないタブの内容を読むには、2 回目の呼び出しが必要です。タブの一覧は最初の応答に含まれます。

この動画 ID、dQw4w9WgXcQ を調べてください。統計情報を取得し、関連動画のうち同じチャンネルのものがあるか確認してください。

1 回の呼び出し、10 クレジット。関連動画は同じ応答に含まれます。

YouTube で「web scraping tutorial」を検索してください。アップロード日順に並べ、4 分未満の動画だけを対象にし、チャプターがある結果については各チャプターのタイトルを教えてください。

1 回の呼び出し、10 クレジット。

この動画のドイツ語の文字起こしがあれば取得し、対応している言語を教えてください。

1 回の呼び出し、10 クレジット。

検索では YouTube 独自のフィルタートークンを使用します。エージェントは後処理なしで、再生時間、アップロード日、コンテンツの種類を使って絞り込めます。文字起こしには利用可能な言語トラックの一覧が含まれるため、エージェントは推測せずに言語を選べます。

ページ移動のたびに呼び出しが必要です。検索して 2 回ページ移動し、その後 3 件の文字起こしを取得する調査プロンプトでは、合計 6 回の呼び出しとなり、60 クレジットかかります。無料枠は、自由度の高い大規模なクロールよりも、対象を絞った質問で多く活用できます。

ツール

4 つのツールはすべて読み取り専用です。以下のサンプルは実際の呼び出しから一部を抜粋したもので、数値は YouTube の更新に応じて変わります。値の形としてご覧ください。各ツール名はエンドポイントのリファレンスにリンクしており、そこにはすべてのフィールドが記載されています。

サンプルはペイロードであり、レスポンス全体ではありません。tools/call の結果には 1 つのテキストブロックが含まれ、そのテキスト自体は url、status、text、json を含む JSON で、スクレイピングしたデータは json の下にあります。生の JSON-RPC レスポンスでは、パスは result.content[0].text で、これを解析してから .json を取得します。チャットクライアントはこれを自動で展開しますが、エンドポイントと直接やり取りするコードでは展開されません。

YouTube の検索結果を取得する

hasdata_youtube_search_getYoutubeSearchResults

YouTube を検索し、結果の種類ごとに分割された検索結果ページ全体を返します。

検索結果ページは、videoResults、shortsResults、inlineShortsResults、playlistResults、channelResults、shelves に分かれており、有料掲載は adsResults と sponsoredResults に含まれます。どのブロックが含まれるかはクエリによって異なり、報告する内容がないブロックは空ではなく省略されます。反復処理の前にキーの有無を確認してください。searchInformation には合計が含まれ、pagination.nextPageToken を次のリクエストで paginationToken として渡します。広告がオーガニック検索結果の配列に混在することはありませんが、スキップすべき広告用ブロックが 2 つあります。

{
  "positionOnPage": 1,
  "videoId": "GuTcle5edjk",
  "title": "you need to learn MCP RIGHT NOW!! (Model Context Protocol)",
  "viewsOriginal": "1.6M views",
  "views": 1653824,
  "length": "38:40",
  "publishedDate": "11 months ago",
  "extensions": ["4K"],
  "chapters": [
    { "title": "Intro", "time": "0:00" },
    { "title": "Problem: LLMs Suck at Accessing Code", "time": "0:40" }
  ],
  "channel": { "name": "NetworkChuck", "verified": true }
}

ここでは 2 点に注目してください。views は 1.6M views という表示文字列と並んで解析済みの整数として返されるため、接尾辞を解析する必要はありません。また、chapters は動画そのものだけでなく検索結果にも含まれますが、チャプターを持つ動画は一部に限られます。

検索エンドポイントのリファレンスには、エンドポイントで受け付けられるすべての sp および filters__ トークンが記載されています。

YouTube 動画データを取得

hasdata_youtube_video_getYoutubeVideo

ID で指定した 1 本の動画です。

title、thumbnail、channel、publishedDate、lengthSeconds、category、isFamilySafe、isUnlisted のほか、relatedVideos、endScreenVideos、keywords、captions、music、socialLinks の各配列を返します。description は、全文を含む content と、リンクやハッシュタグごとに startIndex、length、text、url を含む links 配列を保持するオブジェクトです。text フィールドには投稿者が記述したリンクがそのまま格納され、url には YouTube のリダイレクト用 URL が格納されます。これは、説明欄からスポンサーやアフィリエイトのリンク先を抽出する場合に重要です。

以下のサンプルをコピーする前に、ツールごとにフィールド名を確認してください。検索結果とチャンネル検索結果では、解析済みの数値が views に、表示用の文字列が viewsOriginal に格納されます。このレスポンスでは逆になっており、views には文字列、extractedViews には数値が格納されます。同じ逆転は likes と subscribers にも当てはまります。間違えると、ここでは item.views > 100000 が文字列を比較してもエラーにならず、意図しない結果になります。

{
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "views": "1,806,075,152 views",
  "extractedViews": 1806075152,
  "likes": "19M",
  "extractedLikes": 19344370,
  "publishedDate": "Oct 24, 2009",
  "lengthSeconds": 214,
  "category": "Music",
  "channel": { "name": "Rick Astley", "subscribers": "4.53M subscribers", "extractedSubscribers": 4530000 }
}

YouTube チャンネルデータを取得

hasdata_youtube_channel_getYoutubeChannel

ID またはハンドルで指定したチャンネルを、一度に 1 つのタブずつ取得します。

デフォルトのタブでは、channelInfo、featuredVideo、sections を返します。ほかのタブでは、それぞれ異なる形式のデータを返します。channelInfo には、ハンドル、アバター、バナー、説明、チャンネルのキーワード、チャンネルの rssUrl が含まれており、チャンネルをポーリングせずに更新を追跡できます。

以下のサンプルの availableTabs 配列には表示用ラベルが含まれていますが、これらは tab に指定できる値ではありません。Home、Live、Courses、Search には対応するパラメーター値がなく、残りは小文字にする必要があります。リストを読み取って各項目を順に処理するエージェントは、最初の項目で失敗します。

{
  "channelInfo": {
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "name": "Google for Developers",
    "handle": "@GoogleDevelopers",
    "rssUrl": "https://www.youtube.com/feeds/videos.xml?channel_id=UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "isFamilySafe": true,
    "availableTabs": ["Home", "Videos", "Shorts", "Live", "Courses", "Playlists", "Posts", "Search"]
  }
}

YouTube 動画のトランスクリプトを取得

hasdata_youtube_transcript_getYoutubeTranscript

動画のタイムスタンプ付きトランスクリプトです。

言語を信頼する前に、レスポンスの selected を確認してください。動画に含まれていない languageCode を指定しても、エラーにも空の結果にもならず、デフォルトのトラックにひそかにフォールバックします。リストの各項目には languageName と languageCode が含まれており、同じ言語が、人手で作成されたものと type に asr が設定されたものの 2 回表示されることがあります。

{
  "transcript": [
    { "startMs": 320, "endMs": 18800, "snippet": "[Music]", "startTimeText": "0:00" },
    { "startMs": 18800, "endMs": 21800, "snippet": "We're no strangers to", "startTimeText": "0:18" }
  ],
  "availableTranscripts": [
    { "languageName": "English", "languageCode": "en" },
    { "languageName": "English", "languageCode": "en", "type": "asr", "selected": true },
    { "languageName": "German (Germany)", "languageCode": "de-DE" },
    { "languageName": "Japanese", "languageCode": "ja" }
  ]
}

プロンプトとリソース

サーバーには2つのプロンプトが用意されています。クライアントは、ユーザーにツール呼び出しを作成してもらう代わりに、そのまま使えるワークフローとして提供できます。

サーバーはこれらに加えて、受け付ける値が固定リストになっているパラメーターごとに、10個のリソースを公開します。拒否された呼び出しから値の使い方を学ぶより、リソースを読むほうが効率的で、クレジットも消費しません。各URIはhasdata://youtube/<parameter>です。

どちらのリストもAPIキーなしで提供されるため、クライアントはユーザーが登録する前に読み取ることができます。

エラーと失敗時の動作

ツール呼び出しで HTTP エラーコードがクライアントに返されることは、ほとんどありません。MCP レイヤーは 200 を返し、isError を true に設定して、理由をテキストとして結果に含めます。エージェントは、ステータス行が表示されると思われる場面でメッセージを読み取ります。

キーが間違っている場合、接続エラーではなくツールの出力として示されます。 tools/list は空でないキーなら何でも受け付け、4 つすべてのツールを返すため、クライアントはハンドシェイクを完了し、正常な状態を表示します。その後、最初のツール呼び出しで isError: true とテキスト HasData API error: 401 Unauthorized が返されます。フローのそれ以前の段階では問題が報告されないため、この文字列に注意してください。

キーがない場合に限り、実際の HTTP エラーが発生します。 どのツールよりも先に認証が実行されるため、接続自体が 401 で失敗します。CORS ヘッダーが設定されているので、ブラウザクライアントは不透明なネットワークエラーではなく、ステータスを読み取れます。

ツールのスキーマに合わない引数は、スクレイピングが始まる前に拒否されます。 サーバーは isError: true と、問題のフィールドを示すテキスト MCP error -32602: Input validation error を返します。データは取得されず、課金もされません。メッセージにはフィールド名が示されますが、有効な値は示されないため、上記のパラメーター表を参照してください。

呼び出しが成功したものの、何も見つからなかった場合は、見落としやすいケースです。 requestMetadata.status が ok に設定された通常の結果として返され、データキーが存在しないだけです。結果が空だったことを示す内容は、レスポンス本文にありません。エラーの有無ではなく、必要なフィールドがあるかどうかを確認してください。

プラットフォームが受け付けない識別子を指定すると、 requestMetadata.status が error に設定されて 400 が返されます。存在しないチャンネルのハンドルを指定すると、通常この状況になります。

データを含む結果には、サポートへの問い合わせで伝えると役立つ requestMetadata.id も含まれます。

料金、無料枠、上限

YouTube の各ツールは、呼び出しが成功するごとに 10 クレジットかかります。レスポンスのサイズによって料金は変わりません。検索結果が 1 件のページも、1 ページ分すべての検索結果がある場合と同じ料金です。

無料枠は毎月 1,000 クレジット、カード登録不要で、YouTube を 100 回呼び出せます。請求サイクルごとに更新されるため、呼び出し頻度が低いエージェントなら、無料枠のまま使い続けられます。

有料プランは、200,000 クレジット（20,000 回の呼び出し）が利用できる月額 59 ドルから始まります。利用量が増えるほど単価は下がり、エントリープランでは呼び出し 1,000 回あたり 2.95 ドル、Basic では1.19 ドル、Growth ティアでは0.83 ドルです。最新の料金は料金ページをご覧ください。

同時実行数もプランによって決まります。無料枠では一度に 1 件、Startup では 5 件、Basic では 15 件、Growth ティアでは 50 件から 500 件まで実行できます。無人で実行するものでは、上限超過のケースに備えてください。呼び出しを並列に実行するエージェントは、上限にすぐ達する可能性があります。

200 以外のステータスで返されたリクエストには課金されません。何も見つからなかった成功した呼び出しには課金されます。

ツールの選択

apis クエリパラメーターによって、エージェントに表示されるツールが決まります。ツールが少ないほど、ツール定義に使うコンテキストが減り、モデルが誤ったツールを選ぶ可能性も低くなります。

?apis=youtube                    the four tools in this repo
?apis=youtube,google_serp        add Google search
?apis=youtube,tiktok,instagram   a social research bundle

このパラメーターには youtube のようなプロバイダー名や、google_maps_search のような個別の API 名を指定します。スペルミスのある名前は無視されます。すべての名前が間違っている場合、リクエストは 400 で失敗し、認識できなかった名前とすべての有効な値が本文に記載されます。パラメーターを省略すると、同じエンドポイントですべての HasData ツール 57 個が表示されます。

比較

公式の YouTube Data API v3 と比較した場合：

最後の 2 行は重要です。1 日の上限で利用量をまかなえ、照会するチャンネルを自分で所有している場合は、公式 API のほうが安価なので、そちらを利用してください。

他の YouTube MCP サーバーの多くは、字幕起こしのみを行います。このサーバーは検索に加え、エンゲージメント数を含む動画の取得や、チャンネルタブの巡回も行うため、エージェントは別のサーバーを使わずに調査をひと通り実行できます。

このサーバーでできないこと。 コメント、チャンネル管理、アップロード、アナリティクス、非公開データには対応していません。サインアウトした訪問者に表示される情報のみを読み取ります。

FAQ

公式の YouTube MCP サーバーはありますか？

Google は公開していません。YouTube にはファーストパーティの MCP サーバーはありません。どの選択肢も他の開発者が構築したもので、YouTube Data API v3 か公開ページのいずれかを利用しています。このサーバーは HasData がメンテナンスしており、公開ページを読み取るため、Google の認証情報は必要ありません。

YouTube MCP サーバーとは何ですか？

AI クライアントが呼び出せるツールとして YouTube データを提供するサーバーです。クライアントは Model Context Protocol 経由でツール呼び出しを送信し、サーバーはデータを取得して構造化 JSON を返します。モデルは結果を使って処理を行い、HTML ページを見ることはありません。このサーバーは 4 つのツールを提供し、リモートで動作します。クライアントは URL に接続するだけで、ローカルプロセスを起動する必要はありません。

YouTube API キーや Google Cloud プロジェクトは必要ですか？

いいえ。必要な認証情報は HasData のキーだけです。ツールは YouTube Data API ではなく YouTube の公開ページを読み取るため、Google Cloud プロジェクトの作成、クォータ申請フォームの記入、OAuth 同意画面の設定は必要ありません。

何かをホストしたり実行したりする必要はありますか？

いいえ。これはストリーミング可能な HTTP を使うリモート MCP サーバーです。インストールするものも、起動状態を保つ必要があるコンテナも、再起動が必要なプロセスもありません。

データはリアルタイムですか、それともキャッシュされていますか？

リアルタイムです。呼び出しごとにリクエスト時点でページを取得し、個別の requestMetadata.id が付与されます。同じ内容で 2 回呼び出した場合も、それぞれ独立して取得され、保存済みのコピーを再生することはありません。再生回数や高評価数などのカウンターはページの内容に追従するため、ページの更新に合わせて変化します。

YouTube のレイアウトが変わるとどうなりますか？

お客様側での対応は不要です。変更を追跡し、レスポンスのスキーマを安定させるため、フィールド名と型は変わりません。値のないフィールドはアイテムに含まれず、null としては返されません。省略可能なフィールドはデフォルト値を指定して読み取ってください。

他の HasData API と組み合わせて使えますか？

はい。apis パラメーターにはリストを指定できます。?apis=youtube,google_serp を指定すると、4 つの YouTube ツールに加えて Google 検索もエージェントで利用できます。パラメーターを省略すると、すべての機能を利用できます。

どの動画でも字幕起こしを取得できますか？

字幕起こしが用意されている動画に限ります。availableTranscripts で、リクエスト前に利用可能なものを確認できます。

キーを貼り付けずに OAuth でサインインできますか？

対応しているクライアントなら可能です。Claude Desktop と Cursor では、エンドポイントをコネクターとして追加してサインインできます。無人エージェントやスクリプトでは、x-api-key ヘッダーを使用してください。

コンプライアンスと個人データ

HasData がアクセスするのは、一般に公開されているデータのみです。プラットフォームの利用規約により自動アクセスが制限される場合があり、コンプライアンスへの対応はご自身の責任となります。収集するデータに個人情報が含まれる場合は、GDPR、CCPA、またはお住まいの地域の同等の規則に基づき、適法な根拠があることを確認してください。

HasData のリンク

開発

このリポジトリには、リモートサーバーの設定とドキュメントが含まれています。ビルド手順はなく、コンテナ化するものもありません。

test/ 内のテストでは、ここでのコミットなしに変更される可能性のある部分、つまりツールの契約を検証します。?apis=youtube が正確に 4 つのツールを返すこと、すべてのツールで必須パラメーターが引き続き宣言されていること、名前が変更されていないこと、使用中のキーが実際に受け付けられることを確認します。最後のチェックでは実際にツールを呼び出すため、10 クレジットかかります。これは、適切な理由で失敗する可能性があるカナリアテストの料金です。

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

同じテストスイートは、上流のツール一覧がこのリポジトリに変更がなくても変わる可能性があるため、プッシュのたびに CI で実行され、さらに週 1 回、スケジュールに従って実行されます。失敗した場合は、ツール一覧が変わった、キーが使えなくなった、またはエンドポイントに到達できなかったことを意味し、どれに該当するかはアサーションのメッセージに示されます。

貢献

ツールの表とレスポンスのサンプルは内容が古くなりやすいため、これらの修正が最も役立ちます。実行した呼び出しと、受け取ったレスポンスを記載してください。フォークからのプルリクエストではキーなしでテストスイートが実行され、ライブチェックは失敗扱いにならずスキップされます。

ライセンス

MIT。詳しくは LICENSE をご覧ください。