youtube-mcp

MCP server for YouTube. Exposes four tools to any MCP client (Claude Desktop, etc.):

Tool	What it does
get_video	Fetch video metadata (title, views, duration, etc.)
get_transcript	Fetch timestamped caption segments (YouTube captions)
search_videos	Search YouTube by keyword, ordered by date or relevance
transcribe_video	Download audio and transcribe locally using Whisper — works when captions are unavailable, no extra API keys

Zero system dependencies. ffmpeg is bundled via static-ffmpeg and downloaded automatically on first use. No Homebrew, no manual installs.

Setup

1. Get a YouTube Data API v3 key

1. Go to console.cloud.google.com
2. Create a project → APIs & Services → Enable APIs → search "YouTube Data API v3" → Enable
3. APIs & Services → Credentials → Create Credentials → API Key
4. Copy the key

2. Install

git clone https://github.com/sparsh-gaurav/youtube-mcp.git
cd youtube-mcp
pip install -e ".[dev]"

3. Configure

cp .env.example .env
# edit .env and paste your YOUTUBE_API_KEY

4. Run tests

pytest -v

5. Wire up Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "youtube": {
      "command": "/path/to/youtube-mcp/.venv/bin/python3",
      "args": ["-m", "youtube_mcp.server"],
      "cwd": "/path/to/youtube-mcp",
      "env": {
        "YOUTUBE_API_KEY": "your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You can then ask things like:

"Search the latest YouTube videos about Ram Mandir fund scam and summarise them"
"Get the transcript for video dQw4w9WgXcQ"
"Transcribe this video even though it has no captions: ..."
"What is the view count and duration of this YouTube video?"

First-run notes

• transcribe_video first call: downloads the Whisper base model (~145 MB) to ~/.cache/whisper and the bundled ffmpeg binary (~60 MB) to the Python package directory. Both are cached — subsequent calls are fast.
• Temp files: audio downloaded during transcription is stored in a system temp directory and deleted automatically after each call, whether it succeeds or fails.

Tools

get_video(video_id: str) -> VideoMetadata

Field	Type	Description
id	str	YouTube video ID
title	str	Video title
description	str	Full description
channel_title	str	Channel name
view_count	int	Total views
like_count	int | None	Likes (None if hidden by creator)
duration	str	ISO 8601 duration (e.g. PT3M33S)
published_at	str	ISO 8601 publish date
thumbnail_url	str	Default thumbnail URL

---

get_transcript(video_id: str, language: str | None = None) -> list[TranscriptSegment]

Returns YouTube's caption segments when available.

Field	Type	Description
start	float	Segment start time (seconds)
duration	float	Segment duration (seconds)
text	str	Caption text

language: BCP-47 code (e.g. "en", "hi"). Defaults to first available language.

---

search_videos(query: str, max_results: int = 5, language: str | None = None, order: str = "date") -> list[VideoSearchResult]

Searches YouTube via the Data API v3. Returns newest-first by default.

Field	Type	Description
video_id	str	YouTube video ID
title	str	Video title
description	str	Snippet description
channel_title	str	Channel name
published_at	str	ISO 8601 publish date
thumbnail_url	str	Default thumbnail URL

max_results: 1–50, default 5.
order: date (default), relevance, viewCount, rating.
language: BCP-47 relevance hint (e.g. "en", "hi"). Optional.

---

transcribe_video(video_id: str, language: str | None = None) -> WhisperTranscript

Downloads audio and transcribes locally using OpenAI Whisper (base model). No API key required.

Field	Type	Description
video_id	str	YouTube video ID
text	str	Full transcript text
segments	list[WhisperSegment]	Timestamped segments

Each WhisperSegment:

Field	Type	Description
start	float	Segment start time (seconds)
end	float	Segment end time (seconds)
text	str	Transcribed text

language: BCP-47 hint for Whisper (e.g. "en", "hi"). Auto-detected if omitted.

---

Project structure

src/youtube_mcp/
  server.py       # MCP entry point, tool registry
  api.py          # YouTube Data API v3 wrapper (get_video, search_videos)
  transcript.py   # youtube-transcript-api wrapper (get_transcript)
  whisper.py      # yt-dlp + local Whisper transcriber (transcribe_video)
  models.py       # Pydantic models
tests/
  test_api.py
  test_transcript.py
  test_whisper.py