Skip to main content
Glama
Sign In
youtube-mcp

youtube-mcp

by brian-huanggg
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Youtube MCP

Fast, minimal, and reliable YouTube MCP for AI agents.

Banner

Install

Claude Code

claude mcp add youtube -- uvx youtube-watch-mcp

Before publish (local dev): point uvx at the checkout instead: claude mcp add youtube -- uvx --from /path/to/youtube-mcp youtube-watch-mcp

Claude Desktop / Codex / other MCP clients

Add to the client's MCP config:

{
  "mcpServers": {
    "youtube": {
      "command": "uvx",
      "args": ["youtube-watch-mcp"]
    }
  }
}

CLI only

uvx --from youtube-watch-mcp youtube-watch-mcp-cli info "https://youtu.be/VIDEO_ID"

That's it. uvx pulls youtube-watch-mcp, yt-dlp, and dependencies into an isolated environment automatically. Nothing to install globally.

Optional: ffmpeg on PATH is required only for --asr (speech-to-text on caption-less videos). Core transcript extraction needs nothing.

Related MCP server: youtube-mcp

Optional API key

A YouTube Data API key is not needed to read videos. Add one only to enable cross-YouTube search:

claude mcp add youtube -e YOUTUBE_API_KEY=your_key -- uvx youtube-watch-mcp

Transcript extraction never uses the key (YouTube only allows caption download for video owners).

Tools

Tool

Returns

Purpose

get_info(url)

title, duration, chapters, has_captions

Cheap probe before fetching.

get_transcript(url, asr=False)

file path + word count + preview

Clean transcript to disk. Returns path, not full text.

search_transcript(url, query)

timestamped snippets

Grep a long video without loading it all.

get_segment(url, start, end)

text slice

Read one time range.

Design principle: pull, don't dump. Transcripts write to a local cache file; tools return a path and a short preview. The agent reads or searches on demand — long videos never flood the context.

/get_info $url
/get_transcript $url
/search_transcript $url
/get_segment $url

Architecture

Adapters (thin):   cli.py   mcp_server.py   skill
                        │  call
Core (all logic):  fetch → clean → chunk → cache
                        │  uses
Backends:          youtube-transcript-api · yt-dlp · faster-whisper

Fetch fallback chain:

  1. youtube-transcript-api — fastest, no download

  2. yt-dlp auto-captions

  3. yt-dlp manual captions

  4. --asr: audio → local faster-whisper

On yt-dlp failure the engine self-updates yt-dlp and retries once — most breakage is a stale yt-dlp.

Caching: results are keyed by video ID under ~/.cache/youtube-mcp/<id>/. Repeat calls are instant.

Cleaning: auto-captions are de-duplicated (rolling-caption overlap removed), stripped of timestamps and [Music] noise, and whitespace-collapsed before the agent ever sees them.

Requirements

  • Python 3.11+ (managed automatically by uvx)

  • ffmpeg — optional, only for --asr

Docs

  • FAQ — keyless? no-caption videos? --from gotcha? long-video handling?

  • Architecture — core/adapter split, fetch chain, the cleaning moat, cache.

License

MIT

Available Tools

4 tools
get_infoA

Cheap probe of a YouTube video: title, duration, chapters, caption availability.

Call this first to decide whether to fetch a transcript and how to read it.

Inputs: url (required).

get_segmentA

Return transcript text for the time range [start, end) in seconds.

Inputs: end (required), url (required), start (required), lang.

get_transcriptA

Fetch a cleaned transcript and write it to a local file.

Returns the file path plus a short preview and stats — NOT the full text. Read the file, or use search_transcript / get_segment, to pull detail on demand.

Inputs: url (required), lang.

search_transcriptA

Find cues matching a query. Returns timestamped snippets only.

Use for long videos: locate the relevant moments without loading everything.

Inputs: url (required), query (required), lang. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: get_info probes metadata, get_transcript fetches and saves the transcript, search_transcript finds matching cues, and get_segment extracts a specific time range. No two tools overlap in purpose.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with lowercase and underscores: get_info, get_transcript, search_transcript, get_segment. The style is uniform and predictable.

    Tool Count5/5

    Four tools is an appropriate size for a focused transcript retrieval and search server. Each tool serves a distinct step in the workflow without unnecessary redundancy.

    Completeness5/5

    The tool set covers the full lifecycle: probe video info, fetch transcript, search within it, and extract specific segments. There are no obvious gaps for the stated purpose of retrieving and navigating video transcripts.

    Resources

    Related MCP Connectors

    Related MCP Servers