MCP Youtube Transcript

What @sinco-lab/mcp-youtube-transcript does

@sinco-lab/mcp-youtube-transcript exposes YouTube transcript retrieval through the Model Context Protocol. It is intended for MCP-compatible clients such as Claude Desktop, Cursor, Cline, and Codex, with requests typically executed on the user's machine through npx rather than sent through a remote MCP proxy.

The server accepts either a YouTube video URL or video ID. It can retrieve the best available caption track automatically or use a requested language code. Returned text can be continuous or split into paragraphs, and a separate operation provides one timestamped line for each caption segment.

It also provides lightweight video inspection: one tool returns basic metadata together with available transcript languages, while another lists those languages without returning the transcript itself. This makes it possible to check caption availability before requesting a particular language.

How it works

The server uses caption data exposed through YouTube's web and Android client mechanisms rather than an official public API for arbitrary video captions. Its fetching and parsing logic handles several caption formats, including srv3, classic XML, json3, and VTT.

Processing includes HTML entity decoding, punctuation and whitespace normalization, timestamp handling, overlap detection, and automatic paragraph segmentation. An Android InnerTube fallback is included for some current YouTube caption responses. The implementation reports conditions such as invalid video identifiers, unavailable captions, unsupported language selections, network failures, rate limits, and empty responses caused by YouTube client enforcement.

Because YouTube can reject requests from some networks, hosted environments, or remote MCP providers, running the package locally is part of its intended usage pattern.

Setup and configuration

Node.js 18 or newer is required. For a local setup, add an MCP server entry that launches the package with npx:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": ["-y", "@sinco-lab/mcp-youtube-transcript"]
    }
  }
}

The same command structure can be used with Claude Desktop, Cursor, or Cline. Restart the client after changing its configuration. The repository also includes a production Dockerfile; build it with docker build -t mcp-youtube-transcript . and configure the client to run docker run --rm -i mcp-youtube-transcript.

For development or inspection, clone the repository, install dependencies, build the TypeScript project, and launch the compiled entry point through MCP Inspector. Claude Desktop logs can be followed from its MCP log directory. If a cached npx installation causes problems, removing ~/.npm/_npx provides a clean package cache.

Tools and capabilities

• get_transcripts: fetches transcript text, with optional language selection and paragraph formatting.
• get_transcript: compatibility alias for get_transcripts.
• get_timed_transcript: returns caption lines with timestamps such as [00:00:01.250].
• get_video_info: returns basic video metadata and available transcript languages.
• get_available_languages: lists caption languages for a video.
• Supports automatic selection of the best available caption track when lang is omitted.

Limitations and notes

The server depends on captions being available for the requested YouTube video and language. YouTube does not offer an official public API for downloading arbitrary video captions, so access relies on internal caption responses that may change or be refused.

Network location matters: YouTube may block requests from certain hosted environments, remote MCP providers, or other networks. Rate limiting and empty caption responses are handled as explicit error conditions. The server is licensed under MIT.