YouTube Transcript MCP

YouTube Transcript MCP Server

タイムスタンプ付きの一般公開されている YouTube 字幕トラックを MCP クライアントが取得できる、セルフホスト可能な Model Context Protocol サーバーです。音声の文字起こしは行いません。Claude Desktop などのローカル stdio クライアントのほか、公開 HTTPS MCP エンドポイントを介した ChatGPT および Claude の Web/API に対応しています。

インテグレーションの仕組み

接続モードは 2 つあります。

• ローカルの Claude Desktop、Cursor、VS Code などのクライアント： クライアントが MCP stdio 経由で dist/index.js を起動します。YouTube へのリクエストはお使いのコンピューターから送信されます。
• ChatGPT のカスタム MCP サーバーおよび Claude のリモートカスタムコネクター： これらのクライアントには、公開 https:// URL からアクセス可能な MCP サーバーが必要です。このサーバーをローカルで実行し、トンネルを使ってポート 3000 を公開してください。サーバーは引き続きお使いのコンピューターから YouTube にアクセスするため、YouTube にはクラウド環境のデプロイ IP ではなく、ご家庭の IP アドレスが認識されます。

HTTP エンドポイントでは、公式 MCP SDK の Streamable HTTP トランスポートを使用します。スクリプトやヘルスチェック用に、REST エンドポイントも直接利用できます。

セキュリティに関するお知らせ：公式ホスティング

このプロジェクトはセルフホスト可能です。作者は、公式の公開 MCP サーバーを提供していません。

セキュリティとプライバシーを守るため、このリポジトリをクローンしてご自身でサーバーを実行するか、ご自身が管理するインフラストラクチャに独自のインスタンスをデプロイしてください。

このプロジェクトをホストしていると主張するサードパーティの Web サイトにはご注意ください。 元のプロジェクトと関係があるとは限らず、変更を加えたコードを実行したり、サーバーに送信された情報を収集したりする可能性があります。

公式ソースコード： https://github.com/windows10fan648/youtube-transcript-mcp

作者は、非公式のサードパーティによるデプロイのセキュリティ、プライバシー、動作について責任を負いません。

クイックスタート

git clone https://github.com/windows10fan648/youtube-transcript-mcp.git
cd youtube-transcript-mcp
npm install
npm run build
npm test

MCP Registry への公開

このリポジトリには、公式の MCP Registry 用の server.json マニフェストが含まれています。このマニフェストはローカルの stdio パッケージについて記述しており、このプロジェクトは公式にホストされるリモートエンドポイントを提供していません。

初めて Registry に公開する前に：

1. スコープ付き npm パッケージ @fakasys/youtube-transcript-mcp が利用可能で、公開できることを確認します。package.json のパッケージ名と、server.json の packages[0].identifier は一致している必要があります。
2. npm に認証してから、パッケージをビルドして確認します：

   npm install
   npm run build
   npm pack --dry-run
   npm publish --access public
   

3. MCP Registry のリリースから公式の mcp-publisher CLI をインストールします。
4. マニフェストを検証し、GitHub に認証してから公開します：

   mcp-publisher validate
   mcp-publisher login github
   mcp-publisher publish
   

package.json の mcpName の値は、server.json の name と一致している必要があります。リリースごとに、package.json と server.json のパッケージバージョンを同期してください。Registry のメタデータを公開する前に、npm パッケージを公開してください。

stdio 経由の Claude Desktop

以下を Claude Desktop の設定ファイルに追加します：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

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

絶対パスを指定して Claude Desktop を再起動し、YouTube URL の文字起こしを Claude に依頼してください。このモードはローカル専用で、Claude Web からサーバーを利用することはできません。

HTTPS 経由の ChatGPT および Claude ウェブ版／API

MCP HTTP サーバーを起動します。

npm run serve

別のターミナルで、公開 HTTPS トンネルを作成します。具体的には Tailscale Funnel を使用します。

tailscale funnel --bg 3000

生成された URL の末尾に /mcp を付けて使用します。例：

https://<YOUR_DOMAIN.ts.net/mcp

セキュリティ警告：HTTP エンドポイントを公開する前に、MCP_AUTH_TOKEN を設定してください。設定すると、CORS プリフライトを除くすべての HTTP エンドポイントで Authorization: Bearer <token> が必要になります。保護されていないトンネル URL を入手した人は、ツールにアクセスし、サーバーのリソースを消費できる可能性があります。

サーバーが読み取る YouTube セッション Cookie は、サーバー側の YOUTUBE_COOKIE 環境変数（旧式の COOKIE／YT_COOKIE 環境変数へのフォールバックあり）からのみ取得します。呼び出し元は、クエリパラメーター、リクエストボディ、ヘッダーを通じて Cookie を指定または上書きできません。これらの Cookie をコミットしたり、公開したりしないでください。

ChatGPT

ChatGPT でカスタムコネクター／MCP サーバーの画面を開き、HTTPS の /mcp URL を追加して、読み取り専用ツールを有効にします。ChatGPT の画面やワークスペースによっては、カスタム MCP サーバーの追加、またはプラグインの作成という表示になっている場合があります。次に、https://www.youtube.com/watch?v=... の利用可能な文字起こし言語を一覧表示し、スペイン語で要約してください。 と尋ねます。ChatGPT は最初に言語一覧ツールを呼び出し、該当するコードを選択してから文字起こしを取得できます。

このサーバーは LLM を実行せず、API キーも必要ありません。要約ツールは文字起こしを取得し、要約の指示とともに ChatGPT に返します。ChatGPT 自体がツールの結果を読み取り、会話で使用しているモデルを使って要約を作成します。

OpenAI API では、同じ URL を使ってリモート MCP ツールを設定します。このサーバーは Streamable HTTP に対応しており、文字起こしを MCP のテキストコンテンツとして返します。

Claude ウェブ版、Claude Desktop のリモートコネクター、Claude API

Claude で カスタマイズ → コネクター → カスタムコネクターを追加 を開き、公開 /mcp URL を入力します。MCP_AUTH_TOKEN が設定されていない場合は サインインしない を選択します。認証が有効な場合は、ベアラートークンを送信するようにコネクターを設定してください。Claude のリモートコネクターは Anthropic のインフラストラクチャから接続するため、トンネルを起動したまま、公開アクセス可能な状態にしておく必要があります。

Claude API では、公開 HTTPS URL を使って MCP コネクターを使用し、list_youtube_transcript_languages、get_youtube_transcript、summarize_youtube_transcript ツールを有効にします。ローカルの stdio サーバーは、Claude API または Claude ウェブ版のリモートコネクターから直接接続できません。

REST API に直接接続

同じサーバーで、以下の REST リクエストも利用できます。

MCP_AUTH_TOKEN='replace-with-a-long-random-token' npm run serve

curl -H 'Authorization: Bearer replace-with-a-long-random-token' \
  'http://localhost:3000/mcp?videoIdOrUrl=dQw4w9WgXcQ'

curl -X POST http://localhost:3000/mcp \
  -H 'Authorization: Bearer replace-with-a-long-random-token' \
  -H 'Content-Type: application/json' \
  -d '{"videoIdOrUrl":"dQw4w9WgXcQ","format":"text"}'

ツールのリファレンス

get_youtube_transcript

• videoIdOrUrl — 必須の YouTube URL または 11 文字の動画 ID です。視聴ページの URL、youtu.be、ショート動画、埋め込み、ライブ配信、モバイル向け URL に対応しています。
• lang — 任意の ISO 639-1／BCP-47 言語コードです。en、pt-BR、es-419、zh-Hans などの地域別コードや文字体系コードも指定できます。サーバーは公開されている字幕トラックから完全に一致するものを選択し、利用できない場合はエラーを返します。別の言語に無断で置き換えることはありません。

このツールは、タイムスタンプ付きのプレーンテキストを返します。例：

[1s] [♪♪♪]
[18s] We're no strangers to love
[22s] You know the rules and so do I

summarize_youtube_transcript

• videoIdOrUrl — 必須の YouTube URL または 11 文字の動画 ID です。
• lang — 任意の文字起こし言語コードです。pt-BR や zh-Hans などの地域別コードや文字体系コードも指定できます。ここで行われるのは字幕の取得であり、要約は接続先の AI が行います。
• style — 接続先の AI クライアントに対する任意の指示で、brief、detailed、bullets を指定できます。

これはクライアント支援型のツールです。字幕を取得しますが、音声の文字起こしを行ったり、OpenAI、llama.cpp、Ollama、その他のモデルをそれ自体で呼び出したりすることはありません。

list_youtube_transcript_languages

• videoIdOrUrl — 必須。YouTube URL、または11文字の動画IDです。

YouTube が公開している字幕トラックを返します。たとえば、{ "code": "zh-Hans", "name": "Chinese (Simplified)", "kind": "standard", "isAutoGenerated": false } のような形式です。返された正確な code を lang として get_youtube_transcript または summarize_youtube_transcript に渡してください。指定した言語コードが利用できない場合、サーバーは利用可能な言語コードを一覧表示するエラーを返します。特定の字幕トラックをリクエストする前に、このツールで利用可能な言語を確認してください。

YouTube へのアクセスと制限事項

このプロジェクトは、YouTube が公開している自動生成字幕を含む字幕トラックを読み取ります。音声の文字起こしや、非公開動画、字幕が無効になっている動画、年齢制限、YouTube 認証の回避は行いません。YouTube 公式の Data API で字幕トラックを操作するには認証が必要です。このサーバーは代わりに、YouTube のプレーヤー字幕データと非公式の Node 文字起こしライブラリを使用します。

クラウドホスト環境へのデプロイで YouTube によるチャレンジが発生した場合は、ローカルの stdio またはローカルトンネルを使用してください。クラウド環境で実行する必要がある場合は、YOUTUBE_COOKIE をサーバー環境にのみ設定してください。URL、リクエスト本文、または呼び出し元が制御するヘッダー内の Cookie は意図的に無視されます。

HTTP リクエストの JSON 本文の上限は 1 MB で、サーバー側でリクエストとヘッダーのタイムアウトが設定されています。PORT は 1 から 65535 までの整数である必要があります。

テスト

npm run build
npm test
npm run serve

ライセンス

ISC