# @sinco-lab/mcp-youtube-transcript [Health: Active]

**Category:** 🌐 Social Media  
**Repository:** https://github.com/sinco-lab/mcp-youtube-transcript  
**GitHub Stars:** 39  
**npm Downloads (last month):** 1037  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/sinco-lab-mcp-youtube-transcript

## Description
A server built on the Model Context Protocol (MCP) that enables direct downloading of YouTube video transcripts, supporting AI and video analysis workflows.

## Tools
Capabilities this server exposes over MCP:

- **get_transcripts** — Extract and process transcripts from a YouTube video.

**Parameters:**
- `url` (string, required): YouTube video URL or ID.
- `lang` (string, optional): Language code for transcripts (e.g. 'en', 'uk', 'ja', 'ru', 'zh'). If omitted, the best available caption track is used.
- `enableParagraphs` (boolean, optional, default false): Enable automatic paragraph breaks.

**IMPORTANT:** If the user does *not* specify a language *code*, **DO NOT** include the `lang` parameter in the tool call. Do not guess the language or use parts of the user query as the language code.
- **get_transcript** — Alias of `get_transcripts` for compatibility with other YouTube transcript MCP servers. Extract and process transcripts from a YouTube video.

**Parameters:**
- `url` (string, required): YouTube video URL or ID.
- `lang` (string, optional): Language code for transcripts. If omitted, the best available caption track is used.
- `enableParagraphs` (boolean, optional, default false): Enable automatic paragraph breaks.

**IMPORTANT:** If the user does *not* specify a language *code*, **DO NOT** include the `lang` parameter in the tool call.
- **get_timed_transcript** — Extract a timestamped transcript from a YouTube video. Use this when the user needs quotes, chapter-like notes, or time-coded references.

**Parameters:**
- `url` (string, required): YouTube video URL or ID.
- `lang` (string, optional): Language code for transcripts. If omitted, the best available caption track is used.
- **get_video_info** — Fetch basic YouTube video metadata and available transcript languages without returning the full transcript.
- **get_available_languages** — List available transcript languages for a YouTube video. Use this before retrying with a specific language code.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## 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`:

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/sinco-lab-mcp-youtube-transcript/readme_