Skip to main content
Glama
deenesjakoruzh
PakmanGames

yt-mcp

by PakmanGames
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

yt-mcp

AIアシスタントにYouTube動画の深いマルチモーダル認識能力を与える、完全にローカルで動作するMCP（Model Context Protocol）サーバーです。APIキーは不要です。 すべての処理は、yt-dlp、OpenAI Whisper、FFmpeg、PySceneDetect、librosaを使用してデバイス上で実行されます。

注: このリポジトリには、Gemini APIを使用する実験的なTypeScriptサーバー（src/）も含まれています。そのサーバーは現在開発が行われておらず、Pythonローカルサーバー（server/）が主要な実装となります。

目次

Related MCP server: YT-NINJA

仕組み

YouTube URL
    │
    ▼
yt-dlp ──────────────── download video.mp4
    │                   extract audio.wav (16 kHz mono)
    ▼
Whisper ─────────────── timestamped transcript (word-level)
    │
    ▼
PySceneDetect ────────── detect scene-cut timestamps
    │
    ▼
FFmpeg ──────────────── extract keyframe JPEGs at scene cuts
    │
    ▼
OpenCV ──────────────── pixel-diff animation detection
    │
    ▼
librosa ─────────────── energy · tempo · music vs speech
    │
    ▼
timeline.py ─────────── unified JSON timeline (all signals, time-aligned)

すべての結果は /tmp/yt-analysis-cache/<video_id>/ にキャッシュされます。同じURLを再度呼び出すと即座に結果が返されます。

前提条件

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Verify
ffmpeg -version
python3 --version   # must be 3.10+

インストール

git clone https://github.com/yourusername/yt-mcp.git
cd yt-mcp

# Create and activate a virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate         # Windows

pip install -r requirements.txt

Whisperモデルの重みは、最初の文字起こし呼び出し時に自動的にダウンロードされます（baseで約75MB、largeで約1.5GB）。

MCP統合

MCPクライアントはサーバーをサブプロセスとして起動するため、シェルやvenvを自動的にアクティブ化することはありません。venvのPythonインタープリターの絶対パスを直接指定する必要があります。

venvをアクティブ化した後、インタープリターのパスを確認してください：

source .venv/bin/activate
which python   # e.g. /Users/you/repos/yt-mcp/.venv/bin/python

Claude Code:

claude mcp add -s user yt-mcp -- /path/to/yt-mcp/.venv/bin/python /path/to/yt-mcp/server/main.py

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "yt-mcp": {
      "command": "/path/to/yt-mcp/.venv/bin/python",
      "args": ["/path/to/yt-mcp/server/main.py"]
    }
  }
}

/path/to/yt-mcp をリポジトリをクローンした場所の絶対パスに置き換えてください。 Windowsの場合、インタープリターは .venv\Scripts\python.exe にあります。

ツール

get_video_transcript

OpenAI Whisperを使用してYouTube動画を文字起こしします（完全にローカルで実行）。

パラメータ

型

デフォルト

説明

youtube_url

string

—

YouTubeの完全なURL

model_size

string

base

tiny · base · small · medium · large

レスポンス:

{
  "title": "Video Title",
  "duration": 847,
  "language": "en",
  "full_text": "Welcome to this video...",
  "segments": [
    {
      "t_start": 0.0,
      "t_end": 4.5,
      "text": "Welcome to this video.",
      "words": [{ "word": "Welcome", "start": 0.0, "end": 0.6 }]
    }
  ]
}

get_video_frames

キーフレームをbase64エンコードされたJPEGとして抽出します。シーン検出にはPySceneDetectを、抽出にはFFmpegを使用します。

パラメータ

型

デフォルト

説明

youtube_url

string

—

YouTubeの完全なURL

strategy

string

scene

scene · interval · both

interval

integer

30

フレーム間の秒数（interval または both 戦略用）

レスポンス:

{
  "title": "Video Title",
  "duration": 847,
  "duration_formatted": "14:07",
  "frame_count": 12,
  "strategy": "scene",
  "frames": [
    {
      "t": 0.0,
      "t_formatted": "0:00",
      "keyframe": "<base64 JPEG>",
      "scene_change": false,
      "animation_detected": false
    }
  ],
  "summary": [ /* same list without keyframe bytes — for quick review */ ]
}

get_audio_features

librosaを使用してオーディオ特性を分析します（ローカルで実行）。

パラメータ

型

デフォルト

説明

youtube_url

string

—

YouTubeの完全なURL

segment_duration

integer

30

分析ウィンドウサイズ（秒）

レスポンス:

{
  "title": "Video Title",
  "duration": 847,
  "segment_duration": 30,
  "segments": [
    {
      "t_start": 0.0,
      "t_end": 30.0,
      "energy": "medium",
      "music": false,
      "tempo_bpm": 95.0,
      "rms_db": -22.1
    }
  ]
}

get_full_context

主要ツール。 完全で同期されたマルチモーダルタイムライン（文字起こし + シーン境界 + アニメーション検出 + オーディオ特性）をすべて時間軸に合わせて返します。

パラメータ

型

デフォルト

説明

youtube_url

string

—

YouTubeの完全なURL

include_frames

boolean

false

セグメントごとにbase64キーフレームを埋め込む

model_size

string

base

Whisperモデルサイズ

レスポンス:

{
  "title": "How Transformers Work",
  "channel": "AI Explained",
  "duration": 847,
  "duration_formatted": "14:07",
  "language": "en",
  "description": "In this video...",
  "segments": [
    {
      "t_start": 0.0,
      "t_end": 12.0,
      "transcript": "Welcome to this video on transformers...",
      "keyframe": null,
      "scene_change": false,
      "animation_detected": false,
      "audio": {
        "energy": "low",
        "speech_rate": "normal",
        "music": true,
        "tempo_bpm": 0.0,
        "rms_db": -28.4
      }
    }
  ]
}

コンテキストウィンドウのヒント: まず include_frames=false で get_full_context を呼び出して動画の構造を把握し、その後、特定のタイムスタンプについて get_video_frames を呼び出してください。

サポートされているURL形式

https://www.youtube.com/watch?v=VIDEO_ID
https://youtu.be/VIDEO_ID
https://youtube.com/shorts/VIDEO_ID

環境変数

変数

デフォルト

説明

YT_CACHE_DIR

/tmp/yt-analysis-cache

ダウンロードした動画やオーディオのキャッシュディレクトリ

開発

# Activate the venv first
source .venv/bin/activate

# Run the server directly (stdio mode — same as MCP clients use)
python server/main.py

# Quick smoke test
python -c "
from server.utils.downloader import VideoDownloader
from server.tools.transcript import get_transcript
d = VideoDownloader()
vp, ap, info = d.download('https://www.youtube.com/watch?v=jNQXAC9IVRw')
print(get_transcript(ap)['language'])
"

テスト

Pythonサーバーには、6つのモジュールにわたる164のテストを含む完全なユニットテストスイートがあります。すべてのテストはネットワークアクセスやモデルのダウンロードなしで実行されます。すべての外部依存関係（Whisper、librosa、FFmpeg、PySceneDetect、OpenCV、yt-dlp）はモック化されています。

テスト依存関係のインストール

pip install -r requirements-dev.txt

全スイートの実行

python -m pytest

期待される出力: 164 passed in ~4s

特定モジュールのテスト実行

python -m pytest tests/test_downloader.py   # VideoDownloader + VideoInfo
python -m pytest tests/test_transcript.py   # Whisper wrapper + range helpers
python -m pytest tests/test_frames.py       # FFmpeg, PySceneDetect, OpenCV
python -m pytest tests/test_audio.py        # librosa AudioAnalyzer
python -m pytest tests/test_timeline.py     # build_timeline + speech rate
python -m pytest tests/test_main.py         # all 4 MCP tool handlers

名前による単一テストの実行

python -m pytest tests/test_timeline.py::TestBuildTimeline::test_rapid_cuts_below_min_merged -v

実際の動画に対するライブスモークテスト

以下の例では、プリマドンナ / 星街すいせい（星街すいせい · Suisei Channel, 2:52）を使用しています。これは、多言語Whisper文字起こし、librosa HPSSによる音楽検出、PySceneDetectによる高速シーンカット、OpenCVピクセル差分によるアニメーション検出など、パイプラインのあらゆる層を検証する日本のミュージックビデオです。

from server.utils.downloader import VideoDownloader
from server.tools.transcript import get_transcript
from server.tools.audio import AudioAnalyzer
from server.tools.frames import detect_scene_timestamps

URL = "https://www.youtube.com/watch?v=M1GYqy0tHV0"

d = VideoDownloader()
video_path, audio_path, info = d.download(URL)

print(f"Title:    {info.title}")        # プリマドンナ / 星街すいせい(official)
print(f"Duration: {info.duration:.0f}s")  # 172

transcript = get_transcript(audio_path, model_size="base")
print(f"Language: {transcript['language']}")  # ja

cuts = detect_scene_timestamps(video_path)
print(f"Scene cuts detected: {len(cuts)}")    # typically 30–60 for a music video

analyzer = AudioAnalyzer(audio_path)
seg = analyzer.analyze_segment(0, 30)
print(f"First 30s — energy: {seg['energy']}, music: {seg['music']}")
# energy: 'medium' or 'high', music: True

フィクスチャ、モックパターン、新しいツールのテスト作成など、テストガイドの詳細は docs/testing.md を参照してください。

アーキテクチャ

システム設計、データフロー、新しいツールの追加方法の詳細については、以下を参照してください：

TypeScriptサーバー（アーカイブ済み）

src/ ディレクトリには、動画分析をGemini APIに委譲する実験的なTypeScriptサーバーが含まれています。これは現在開発が行われておらず、参照用としてのみ保持されています。

高速なクラウドベースの動画Q&Aをお探しの場合は、TypeScriptサーバーのアプローチ（YouTube URLを直接Geminiに渡す）が簡単なプロトタイプには適していますが、継続的なメンテナンスが行われるのはPythonサーバーのみです。

APIリファレンスについては docs/typescript-server.md を参照してください。

ライセンス

MIT

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
41dResponse time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

  • YT-NINJA

    satyamkumar420
    F
    license
    B
    quality
    D
    maintenance
    Enables AI-powered YouTube video analysis including transcript management, video summaries, chapter generation, keyword extraction, and playback control. Supports searching videos, retrieving channel/playlist information, and translating transcripts using Google Gemini AI.
    14

  • yt-analysis-mcp

    Legorobotdude
    F
    license
    A
    quality
    C
    maintenance
    Enables analysis of YouTube videos using the Gemini API to generate summaries and answer specific questions via direct URLs. It supports standard videos and shorts, allowing users to interact with video content without requiring manual downloads.
    5
    4

View all related MCP servers

Related MCP Connectors

  • Acornonaut MCP Server

    AI-powered YouTube to flashcards with spaced repetition and Anki export

  • kirbah-mcp-youtube

    Provide token-optimized, structured YouTube data to enhance your LLM applications. Access efficien…

  • Contendeo

    Multimodal video analysis MCP — transcription, vision, and OCR for any video URL.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/PakmanGames/yt-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server