youtube-transcript-mcp

コーディングエージェントがYouTubeビデオのトランスクリプトを読み取って検索できるようにするMCPサーバーです。APIキーもGoogleアカウントも不要で、サインアップも何もありません。YouTubeの公開エンドポイントを通じてキャプションを取得し、生のトランスクリプトのダンプでは得られない小さなものを1つ追加します。それはチャプター要約です。

これはもともと自分用の小さなツールとして始まりました。YouTubeのリンクが含まれる会話に何度も出くわし、その動画が実際に何を言っているのかを知る必要があり、トランスクリプトを貼り付け直すのに時間を無駄にしていました。それが再利用可能なサーバーとなり、Model Context Protocol上で動作するあらゆるものがただ問い合わせられるようになりました。

できること

4つのツールがあります。

• get_transcript(video_url_or_id, languages=["en"], include_timestamps=False) は、完全なトランスクリプトをプレーンテキストとして取得します。完全なYouTube URL（watch?v=、youtu.be、/embed/、/shorts/、/live/）または単なる11文字のビデオIDを受け付けます。

• get_video_metadata(video_url_or_id) は、YouTubeの認証不要のoEmbedエンドポイントを介して、タイトル、チャンネル名、チャンネルURL、サムネイルを返します。アップロード日や完全な説明は意図的に返しません。これらには公式のData APIキーが必要であり、ここでの要点はキーが不要であることだからです。

• search_transcript(video_url_or_id, query, languages=["en"]) は、キーワードまたはフレーズに一致するセグメントを大文字小文字を区別せずに検索し、それぞれに [mm:ss] タイムスタンプを付けて返します。これにより、モデルは動画内で何かが言われた場所を指し示せます。

• summarize_chapters(video_url_or_id, gap_seconds=4.0, min_chunk_seconds=45.0, languages=["en"]) は、トランスクリプトを自然な区切りで大まかな時間ブロックのチャンクに分割して返します。エージェントが1つの巨大な塊を丸ごと処理するのではなく、セクションごとに要約できるようにするためです。これはヒューリスティックであり、YouTubeの実際のチャプターデータではありません。

すべてのツールは、エラーを含むプレーンな文字列を返します（例：「Error: captions are disabled for this video」）。呼び出し側のエージェントに例外が表面化することはなく、スタックトレースが漏れることもありません。

Related MCP server: youtube-mcp

意図的に行わないこと

• キャプションが無効な動画、非公開または利用できない動画、キャプションのないライブストリームでは動作しません。推測する代わりに、その旨を伝えます。

• YouTube Data APIには依存しません。設計上、APIなしではアップロード日や完全な説明を取得できません。

• キャッシュは行いません。同じ動画に対する2回の呼び出しは、毎回再取得します。このツールの実際の用途には十分です。大量に使う必要が出た場合は、キャッシュを追加してください。

セットアップ

Python 3.11+ と uv が必要です。

uv sync

単体で実行して起動を確認します：

uv run server.py

MCP stdio入力を待機するため、クライアントが接続するまで何もしていないように見えます。それは正常です。終了するにはCtrl+Cを押します。

MCPクライアントへの登録

クライアントのMCP設定に追加します。サーバーはstdioで起動されるため、設定はコマンドラインになります。例としてClaude CLIを使用します：

claude mcp add youtube-transcript -- uv --directory /absolute/path/to/youtube-transcript-mcp run server.py

またはJSON設定の場合：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/youtube-transcript-mcp", "run", "server.py"]
    }
  }
}

苦労して得た注意点

• キャプション（自動生成または手動）がある動画のみが動作します。キャプションのない動画は明確なエラーを返します。これは意図的な選択です。空の結果は静かな失敗のように読めますが、エラーはその原因を明示します。

• 言語リストは重要です。languages=["en"] は、英語トラックが存在する場合にそれを取得します。チャンネルが別の言語でのみアップロードしている場合は、その言語コードを渡してください。

• mcp>=1.28.1 に固定し、2.0未満に保ってください。mcp 2.x は mcp.server.fastmcp をリネームし、サーバー起動時にインポートが静かに失敗します。実際に読み込まれるバージョンを使いたいところです。

ライセンス

MIT。LICENSEを参照してください。