youtube-mcp-server

リモート MCP サーバーで、YouTube Data API v3 をツールとして公開し、Streamable HTTP 経由で claude.ai にカスタムコネクタとして追加できるようにします。

依存関係なし。ビルド手順なし。node src/server.js だけで全部です。

ツール

トランスクリプトは意図的に含めていません。captions.download には OAuth および 動画の編集権限が必要なため、API キーで取得できる字幕は自分が所有する動画のものだけです。非公式のスクレイピングライブラリはクラウドIPレンジからブロックされると広く報告されており、このサーバーが動作するのはまさにその環境です。

Related MCP server: mcp-server-youtube

クォータ

プロジェクトには一般バケットで1日あたり10,000ユニットが与えられ、search.list は別のバケットにあり、1日100回の上限があります。このことがツール設計を形作っています。youtube_channel_videos は search.list?channelId= を使わず、channels.list → playlistItems.list → videos.list の順に呼び出します。そのため、チャンネルの閲覧には、1日100回しかない検索の1回ではなく、一般ユニットを3つ消費します。

ローカルで実行

cp .env.example .env        # add your YOUTUBE_API_KEY
export $(grep -v '^#' .env | xargs)
npm start

curl localhost:3000/health

curl -s localhost:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

テスト

npm test

スタブ化した YouTube API に対して、MCP ハンドシェイク全体、両方のトランスポートモード、5つのツールすべて、およびエラーパスを実行します。API キーもネットワークも不要です。

Railway へデプロイ

1. このリポジトリを GitHub にプッシュします。

2. Railway → 新規プロジェクト → GitHub リポジトリからデプロイ → 選択します。

3. 変数 → YOUTUBE_API_KEY を追加します。

4. 設定 → ネットワーク → ドメインを生成します。

5. https://<your-domain>/health が "apiKeyConfigured": true を返すことを確認します。

Railway が PORT を自身で設定します。サーバーは 0.0.0.0 にバインドし、その値を読み取ります。

claude.ai に追加

カスタマイズ → コネクタ → カスタムコネクタを追加 → https://<your-domain>/mcp

OAuth フィールドは不要です — サーバーはデフォルトでは認証なしです。ロックダウンするには、MCP_AUTH_TOKEN を設定し、コネクタのリクエストヘッダーの authorization に Bearer <token> を指定します。

環境変数

設計メモ

ステートレスです。各 POST は自己完結しています — Mcp-Session-Id もセッションマップもありません — そのため、再起動や2番目のレプリカでも「No valid session ID provided」は発生しません。

コンテンツネゴシエーションはリファレンス SDK に従います。クライアントが Accept: text/event-stream を送信した場合は SSE フレーム、それ以外の場合はプレーンな JSON ボディを返します。

/mcp への GET と DELETE は 405 を返します。これは、サーバー発信のストリームも閉じるセッションもないサーバーに対して Streamable HTTP 仕様が期待する動作です。

Origin ヘッダーの検証も DNS リバインディング対策も行いません。これらの防御は localhost にバインドされた MCP サーバー向けのものです。公開デプロイで有効のままにすると Anthropic 自身のリクエストを拒否するため、initialize タイムアウトの一般的な原因になります。

ツールの失敗は JSON-RPC エラーではなく isError: true のコンテンツとして返されます。そのため Claude は何が問題だったかを読み取って調整でき、呼び出しがトランスポート層で途絶えることはありません。

結果は 120k 文字に切り詰められます。claude.ai のツール結果上限 ~150k を下回ります。