YouTube MCP

YouTube MCP

YouTube MCP を使うと、MCP クライアントから YouTube 動画のメタデータ、字幕の文字起こし、コメント、検索結果を取得できます。デフォルトでは YouTube API キーやアカウントは不要です。オプションの公式 YouTube Data API プロバイダーを使う場合は、API キーを使用してメタデータ、コメント、検索を取得できます。

stdio（ローカル）と Streamable HTTP（VPS／リモート）の両トランスポートに対応しています。

アクセスモデル

これは独立した非公式のオープンソースプロジェクトです。YouTube または Google との提携、承認、後援はありません。

• デフォルトの innertube プロバイダーは、YouTube Data API キーを使わずに、非公式／内部の YouTube インターフェースを利用する youtubei.js 経由でメタデータ、コメント、検索を提供します。非公式のアクセス方法は変更、停止、制限、またはブロックされる場合があります。
• これら 3 つのツールで公式 YouTube Data API v3 を利用するには、YT_PROVIDER=api を選択し、ご自身の YOUTUBE_API_KEY を設定してください。
• 文字起こしツールは YT_PROVIDER の設定にかかわらず、常に youtube-transcript-plus を使用します。文字起こしの取得は引き続き非公式であり、公式 Data API の経路や API キーは使用しません。

アクセス方法が用途に適しているかどうかの判断、および適用されるサービス利用規約と法律の遵守は、ユーザーの責任です。ツールとバックエンドの対応、BYOK の設定、制限事項、ソフトウェアライセンスについては、アクセス方法とサービス利用規約をご覧ください。

機能

ツール	説明
search_youtube	アップロード日と人気度で絞り込んで動画を検索します
get_video_info	動画のメタデータ：タイトル、チャンネル、説明、再生時間、再生回数、高評価数、アップロード日、タグ
get_video_comments	投稿者情報、高評価数、YouTube が含める返信を含むコメントスレッド
get_video_transcript	タイムスタンプ付きの文字起こし（手動字幕＋自動生成字幕）
get_transcript_languages	利用可能な手動字幕と自動生成字幕の言語を一覧表示します
get_server_info	サーバーのバージョン、アクティブなプロバイダー、各ツールを提供するバックエンド

要件

• Node.js 22 以降。CI では Node 22.21.0 と Node 24 を確認しています。

デフォルトでは YouTube API キーは不要です。 デフォルトの innertube プロバイダーは、動画情報、コメント、検索に youtubei.js（非公式／内部の YouTube インターフェース）を使用します。文字起こしには常に youtube-transcript-plus を使用します。どちらも API キーや認証は必要ありません。オプションの公式 API については、プロバイダーをご覧ください。

クイックスタート

MCP クライアントから、クローンを作成せずに公開済みパッケージを実行できます。

npx -y @granitebps/youtube-mcp

サーバーは stdio を使用します。stdout は MCP 通信用に確保してください。

クローンしたリポジトリから実行する

サーバーを開発する場合や、クローンを直接使用する場合：

git clone https://github.com/granitebps/youtube-mcp.git
cd youtube-mcp
npm ci
npm run build

コンパイル済みのエントリーポイントを MCP クライアントに指定します。

node /absolute/path/to/youtube-mcp/dist/index.js

ソースを変更するたびに npm run build を実行してください。クライアントの stdio コマンドには src や npm run dev を使用しないでください。stdout にビルド出力が書き込まれると、MCP メッセージが破損する可能性があります。

クライアント設定

各例では、npm パッケージを使用する設定と、ローカルで同等の設定を示します。/absolute/path/to/youtube-mcp はクローンのパスに置き換えてください。設定の項目は環境変数として追加できます。

Claude

npm パッケージを Claude Code に追加します：

claude mcp add youtube -- npx -y @granitebps/youtube-mcp

ローカルビルドの場合：

claude mcp add youtube -- node /absolute/path/to/youtube-mcp/dist/index.js

Claude Code はデフォルトでローカルスコープを使用します。プロジェクト間でサーバーを利用できるようにするには、youtube の前に --scope user を追加します。

Claude Desktop は claude_desktop_config.json（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）から同じサーバーを読み込みます。ファイルを編集した後、アプリを再起動してください。

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@granitebps/youtube-mcp"]
    }
  }
}

ローカルビルドの場合は、command と args を次の内容に置き換えます：

{
  "command": "node",
  "args": ["/absolute/path/to/youtube-mcp/dist/index.js"]
}

Codex

npm パッケージを ~/.codex/config.toml、または信頼されたプロジェクト内の .codex/config.toml に追加します：

[mcp_servers.youtube]
command = "npx"
args = ["-y", "@granitebps/youtube-mcp"]

ローカルビルドの場合：

[mcp_servers.youtube]
command = "node"
args = ["/absolute/path/to/youtube-mcp/dist/index.js"]

ファイルを編集した後、Codex を再起動してください。

OpenCode

npm パッケージを opencode.json または opencode.jsonc に追加します：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "youtube": {
      "type": "local",
      "command": ["npx", "-y", "@granitebps/youtube-mcp"],
      "enabled": true
    }
  }
}

ローカルビルドの場合は、command 配列を次の内容に置き換えます：

{
  "command": ["node", "/absolute/path/to/youtube-mcp/dist/index.js"]
}

Cursor

プロジェクト内の .cursor/mcp.json、またはグローバルで使用する場合は ~/.cursor/mcp.json に npm パッケージを追加します：

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@granitebps/youtube-mcp"]
    }
  }
}

ローカルビルドの場合は、command と args を次の内容に置き換えます：

{
  "command": "node",
  "args": ["/absolute/path/to/youtube-mcp/dist/index.js"]
}

GitHub Copilot (VS Code)

VS Code の settings.json に追加します：

{
  "mcp": {
    "servers": {
      "youtube": {
        "command": "npx",
        "args": ["-y", "@granitebps/youtube-mcp"]
      }
    }
  }
}

---

VPS へのデプロイ（Streamable HTTP）

リモートにデプロイする場合、サーバーは Streamable HTTP トランスポート（非推奨の SSE トランスポートに代わる、現在の MCP 標準）を使用する常時稼働の HTTP サービスとして実行されます。

1. VPS にデプロイする

# On your VPS
git clone https://github.com/granitebps/youtube-mcp.git
cd youtube-mcp
npm ci
npm run build

# Create .env (optional, for HTTP mode)
cp .env.example .env
# Uncomment TRANSPORT=http, PORT, HOST as needed

YouTube はデータセンターの IP アドレスをブロックすることがよくあります。get_video_info が「Sign in to confirm you're not a bot」とともに ACCESS_BLOCKED を返す場合は、YT_PROVIDER=api と YOUTUBE_API_KEY を設定して、公式 API 経由でメタデータ、コメント、検索を提供します。プロバイダーを参照してください。

2. HTTP トランスポートで実行する

# Using --http flag
node dist/index.js --http

# Or using environment variable
TRANSPORT=http PORT=3000 node dist/index.js

# Or using npm script
npm run start:http

サーバーは http://0.0.0.0:3000/mcp でリッスンします。

3. TLS 対応の Nginx リバースプロキシを設定する

server {
    listen 443 ssl;
    server_name mcp.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;

    location /mcp {
        proxy_pass http://127.0.0.1:3000/mcp;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Required for SSE streaming
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding on;
    }
}

無料の TLS 証明書を取得します：

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d mcp.yourdomain.com

4. systemd で実行し続ける

/etc/systemd/system/youtube-mcp.service を作成します：

[Unit]
Description=YouTube MCP Server
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/youtube-mcp
ExecStart=/usr/bin/node dist/index.js --http
Restart=always
RestartSec=5
Environment=TRANSPORT=http
Environment=PORT=3000
Environment=HOST=127.0.0.1

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable youtube-mcp
sudo systemctl start youtube-mcp
sudo systemctl status youtube-mcp

5. MCP クライアントを VPS に接続する

GitHub Copilot (VS Code) — リモート

{
  "mcp": {
    "servers": {
      "youtube": {
        "type": "http",
        "url": "https://mcp.yourdomain.com/mcp"
      }
    }
  }
}

Claude Desktop — リモート

{
  "mcpServers": {
    "youtube": {
      "type": "streamable-http",
      "url": "https://mcp.yourdomain.com/mcp"
    }
  }
}

---

使用例

接続すると、AI エージェントに次のようなことを依頼できます：

• 「この YouTube 動画の情報を取得して：https://www.youtube.com/watch?v=dQw4w9WgXcQ」
• 「動画 ID abc123 の上位コメントを表示して」
• 「この動画の英語の文字起こしを取得して」
• 「https://youtu.be/xyz789 の文字起こしを要約して」
• 「今週アップロードされた Node.js のチュートリアルを、再生回数順に検索して」
• 「先月の React 動画の中で最も人気のあるものを探して」

ツールの応答形式

すべてのツールは次を返します：

• content：チャット形式の MCP クライアント向けの、短く人が読みやすいテキスト
• structuredContent：信頼性の高いフィールドを必要とするエージェント向けの JSON 形式のデータ

このサーバーは意図的に JSON を優先し、テキストを次点としています。ツールの結果をフィルタリング、変換、または連鎖させる必要がある場合、エージェントは structuredContent を優先してください。

get_video_info の出力例：

{
  "content": [
    {
      "type": "text",
      "text": "📹 Example title\n\nChannel: Example channel\n..."
    }
  ],
  "structuredContent": {
    "videoId": "dQw4w9WgXcQ",
    "title": "Example title",
    "description": "Example description",
    "channelName": "Example channel",
    "channelId": "UC123",
    "uploadedAt": "Sep 14, 2017",
    "duration": "3m 33s",
    "durationSeconds": 213,
    "viewCount": "123456",
    "likeCount": "7890",
    "commentCount": null,
    "tags": ["music", "pop"],
    "thumbnailUrl": "https://..."
  }
}

YouTube から提供されなかった値は null となり、"0"、"N/A"、"Unknown" などのプレースホルダーにはなりません。

エラー

失敗時は isError: true が返されます。テキストはコード（❌ [ACCESS_BLOCKED] ...）で始まり、_meta["youtube-mcp/error"] に詳細が含まれます。

{
  "isError": true,
  "content": [{ "type": "text", "text": "❌ [ACCESS_BLOCKED] YouTube requires sign-in to access video C7OQHIpDlvA: Sign in to confirm you’re not a bot" }],
  "_meta": {
    "youtube-mcp/error": {
      "code": "ACCESS_BLOCKED",
      "message": "...",
      "retryable": false,
      "upstream": { "playabilityStatus": "LOGIN_REQUIRED", "reason": "Sign in to confirm you’re not a bot", "accessKind": "login_required" }
    }
  }
}

エラーは structuredContent ではなく _meta に格納されます。MCP SDK クライアントは、エラー結果であっても structuredContent をツールの出力スキーマに照らして検証するためです。

コード	意味
INVALID_INPUT	YouTube URL または 11 文字の動画 ID ではない、または言語コードが無効です
ACCESS_BLOCKED	YouTube がこのクライアントを拒否しました：HTTP 429/403、CAPTCHA、同意ページ、サインイン、またはボットチェック。upstream.accessKind は rate_limited、forbidden、login_required、consent_required、または quota_exceeded（公式 API のクォータ超過）です。動画が存在するか、字幕があるかについては示しません
VIDEO_UNAVAILABLE	YouTube が動画を ERROR、UNPLAYABLE、非公開、またはオフラインと報告しています。upstream.reason は YouTube 独自のテキストです
CAPTIONS_UNAVAILABLE / LANGUAGE_UNAVAILABLE	内部で使用されます。文字起こしツールは、これらをエラーではなく available: false の結果として返します
COMMENTS_UNAVAILABLE	コメントが無効になっているか、YouTube がコメント欄を返しませんでした
PARSE_ERROR	YouTube から応答がありましたが、応答を解釈できませんでした（レイアウトの変更、誤った動画 ID が返されたなど）
LIMIT_EXCEEDED	設定されたサイズ制限に達しました
TIMEOUT	設定された期限を超過しました。基盤となるリクエストは中止されました
CANCELLED	MCP クライアントがリクエストをキャンセルしたか、サーバーがシャットダウンしています
UPSTREAM_ERROR	その他の HTTP またはネットワークの失敗です（retryable: true）

サーバーが独自に再試行することはありません。

プロバイダー

YT_PROVIDER は、get_video_info、get_video_comments、search_youtube のバックエンドを選択します。get_video_transcript と get_transcript_languages は、どのプロバイダーが有効でも常に youtube-transcript-plus を使用します。get_server_info は有効なプロバイダーを報告します。

プロバイダー	選択方法	必要なもの	備考
InnerTube	デフォルト、または YT_PROVIDER=innertube	なし	Data API キーを使わず、youtubei.js を通じて非公式／内部インターフェースを使用します。YouTube は、データセンターの IP（VPS、クラウドなど）からのアクセスを含め、アクセスを制限またはブロックする場合があります
Official API	YT_PROVIDER=api	YOUTUBE_API_KEY	YouTube Data API v3 を使用します。Google Cloud プロジェクトのクォータ、キーの制限、適用されるサービス利用規約の対象となります

このサーバーは字幕に Data API を使用しません。Google の字幕ダウンロードエンドポイントには、OAuth 認証と動画を編集する権限が必要です。API キーだけでは不十分です。文字起こしツールは非公式の youtube-transcript-plus 経由で動作するため、どちらのプロバイダーを使用しても ACCESS_BLOCKED を返す場合があります。

公式 API の使用

独自のキー（BYOK）をご用意ください。キーはユーザー自身のものであり、このプロジェクトが共有の YouTube API キーを配布またはホストすることはありません。これらの設定は、プロセスまたは MCP クライアントの環境変数で指定してください。サーバーは .env ファイルを自動的に読み込みません。

1. Google Cloud コンソールでプロジェクトを作成し、YouTube Data API v3 を有効にして、API キーを作成します。キーをこの API のみに制限することをおすすめします。
2. 次のコマンドでサーバーを起動します。

YT_PROVIDER=api YOUTUBE_API_KEY=your_api_key npx -y @granitebps/youtube-mcp

クォータ（コスト）：デフォルトの割り当ては 1 日あたり 10,000 ユニットで、これとは別に search.list 呼び出しが 1 日あたり 100 回まで許可されます。

ツール	API 呼び出し
get_video_info	videos.list：1 ユニット
get_video_comments	commentThreads.list：1 ページあたり 1 ユニット。page: N はその前の N-1 ページも順に取得するため、N ユニットかかります
search_youtube	search.list（検索の割り当て）に加えて、再生回数と再生時間を取得するための videos.list を 1 回：1 ユニット

デフォルトのプロバイダーと同様に、結果はキャッシュされるため（動画情報は 30 分、コメントは 10 分、検索は 15 分）、繰り返し呼び出してもコストはかかりません。クォータを使い切ると、upstream.accessKind: "quota_exceeded" を含む ACCESS_BLOCKED が返されます。無効なキーまたは無効化された API の場合は、accessKind: "forbidden" を含む ACCESS_BLOCKED が返されます。

デフォルトのプロバイダーとの違い：

• uploadedAt（get_video_info）と publishedAt（コメント、検索）は、「Sep 14, 2017」や「2 days ago」のような表示テキストではなく、ISO 8601 形式のタイムスタンプです
• 検索の viewCount は「1.2K views」ではなく、"1234" のような数値です。また、duration は get_video_info と同じ形式（"3m 5s"）です
• search_youtube は、すべての sortBy と uploadDate の値を正確に適用し、warnings を返すことはありません。videoDuration: "short" は 4 分未満、medium は 4～20 分を意味します（YouTube API の定義）
• get_video_comments が返すのは、各スレッドについて API が含める返信のみ（一部）です。replyCount は返信の総数です

設定

YT_PROVIDER=api の場合の YOUTUBE_API_KEY を除き、すべての設定は任意の環境変数です。値が無効な場合、サーバーは起動時に標準エラー出力へメッセージを表示して停止します。

変数	デフォルト	効果
YT_PROVIDER	innertube	動画情報、コメント、検索に使用するプロバイダー：innertube または api。プロバイダーを参照
YOUTUBE_API_KEY	なし	YouTube Data API v3 の独自キー。YT_PROVIDER=api の場合は必須。それ以外では無視されます
YT_INIT_TIMEOUT_MS	15000	共有 YouTube クライアントの作成期限
YT_REQUEST_TIMEOUT_MS	20000	クライアントの初期化待機を含む、1 回のツール呼び出しにおける上流処理の期限
YT_TRANSCRIPT_MAX_BYTES	5000000	字幕取得時に各レスポンスから読み込む最大バイト数
YT_TRANSCRIPT_MAX_SEGMENTS	50000	1 つのトラックから処理する字幕セグメントの最大数
YT_TRANSCRIPT_PAGE_MAX_SEGMENTS	500	1 回の get_video_transcript 応答で返すセグメントの最大数

期限が切れた場合、またはクライアントがキャンセルした場合、実行中の HTTP リクエストは単に放置されるのではなく、中断されます。

ツールの詳細

search_youtube

• 入力：query（検索テキスト）、maxResults（1～50、デフォルト 10）、sortBy（relevance | date | viewCount | rating）、uploadDate（any | hour | today | week | month | year）、videoDuration（any | short | medium | long）
• 戻り値：content に人が読める形式の概要、structuredContent に構造化 JSON の検索結果
• 注：デフォルトの innertube プロバイダーでは、YouTube 検索は関連度または人気度でのみ並べ替えられ、アップロード日の絞り込みは today 以降のみ適用されます。sortBy: "date" は関連度順を維持し、sortBy: "rating" は人気度順に並べ替え、uploadDate: "hour" は today として適用されます。それぞれの場合、任意の warnings 配列にエントリ（code、message）が追加されます。api プロバイダーはすべてのオプションを正確に適用します

get_video_info

• 入力: video（YouTube URL または動画 ID）
• 戻り値: content に人が読める概要を、structuredContent に durationSeconds を含む構造化 JSON メタデータを返します。YouTube が再生を拒否した場合でも、動画の詳細が提供されていればメタデータを返します

get_video_comments

• 入力: video（URL または ID）、maxResults（1～20、デフォルトは 20）、sortBy（relevance または time）、page（デフォルトは 1）
• 戻り値: content に人が読める概要を、structuredContent に構造化 JSON のコメントスレッド、ページネーション用フィールド、および hasMore を返します
• 注: replies に含まれるのは、YouTube がスレッドに含めている返信のみです。replyCount は返信の総数です。残りの返信を取得するには、スレッドごとに 1 回のリクエストが必要です

get_video_transcript

• 入力: video（URL または ID）、lang（任意の言語コード。省略した場合は最初の手動字幕トラック、手動字幕がない場合は最初の自動生成トラック）、maxSegments（デフォルトは 0：YT_TRANSCRIPT_PAGE_MAX_SEGMENTS が許可する最大数）、startSegment（デフォルトは 0）
• 戻り値: content に人が読める文字起こしを、structuredContent に構造化 JSON のセグメント、プレーンテキスト、およびページネーション用メタデータを返します。hasMore が true の場合は、startSegment = nextStartSegment とし、返された languageCode を lang として指定して続行します。isAutoGenerated は、そのトラックが YouTube の自動字幕かどうかを示します
• 字幕がない場合: available: false と reason: "NO_CAPTIONS"、または reason: "LANGUAGE_UNAVAILABLE" と availableLanguages を返します。アクセス上の問題はエラーとして扱われ、available: false にはなりません
• 注: ある言語に手動字幕と自動字幕の両方がある場合は、手動字幕が返されます
• 注: API キーは不要です — YouTube の内部字幕システムを介して動作します。文字起こしは字幕テキストのみであり、動画の映像を分析したものではありません

get_transcript_languages

• 入力: video（YouTube URL または動画 ID）
• 戻り値: content に人が読める言語一覧を、structuredContent に構造化 JSON の言語メタデータを返します。available: false は、動画を再生できるものの字幕トラックがないことを意味します。アクセス上の問題はエラーとして扱われます

get_server_info

• 入力: なし
• 戻り値: name、version、provider（innertube または api）、authenticated、exactSearchFilters、および各ツールを提供するバックエンドを示すマップ tools

開発

npm test        # builds, then runs the offline test suite (no network access)
npm run check   # tests plus release metadata, package contents, and tarball install checks

CONTRIBUTING.md を参照してください。

リリースの検証

自動テストスイートでは、入力の解析、設定、エラーの分類、キャンセル、コンパイル済みの stdio エントリーポイント、リリースメタデータ、および npm tarball からのインストールを網羅しています。YouTube への呼び出しは一切行いません。YouTube のライブチェックは手動で行い、CI とは別に実施します。

メンテナーは、承認済みタグを使った npm、MCP Registry、および GitHub リリースのプロセスについて、リリースガイドに従います。

レート制限

デフォルトの innertube プロバイダーと文字起こしツールは、非公式の YouTube インターフェースを使用します。Data API のクォータシステムは使用しませんが、これはアクセスが無制限であることを意味するものではありません。

• 自動化された大量の利用により、CAPTCHA が表示されたり、一時的なブロックが発生したりする場合があります
• データセンターの IP アドレス（VPS、クラウド）からのリクエストは、完全にブロックされることがよくあります
• リクエストの間隔を調整しても、アクセスが保証されるわけではなく、サービス規約上の許可が得られるわけでもありません

api プロバイダーには、代わりに Google Cloud プロジェクトの YouTube Data API クォータによる制限が適用されます。プロバイダーを参照してください。

ライセンス

ISC。ソフトウェアライセンスは、YouTube／Google のサービス規約や、取得したコンテンツに関する権利とは別のものです。アクセスガイドを参照してください。