mcp-youtube-transcript

A small Model Context Protocol (MCP) server that fetches YouTube video transcripts so an AI assistant can read, summarize, or search what was said in a video.

It runs over stdio (for Claude Desktop, Claude Code, Cursor, and similar clients) or as a stateless Streamable HTTP server (for Docker or remote use).

Tools

Both tools accept a full YouTube URL (watch?v=, youtu.be/, /embed/, /v/) or a bare 11-character video ID.

get_transcript

Response:

{
  "text": "...",
  "offset": 0,
  "length": 12345,
  "total_length": 12345
}

get_timed_transcript

Response:

{
  "snippets": [{ "text": "hello", "start": 0.0, "duration": 1.2 }],
  "offset": 0,
  "count": 500,
  "total_snippets": 1834
}

Use total_length / total_snippets to decide whether to page for more.

Related MCP server: YouTube Transcripts MCP Server

Install

Requires Node.js 20 or newer.

git clone https://github.com/cchamp-msft/mcp-youtube-transcript.git
cd mcp-youtube-transcript
npm install
npm run build

The server entry point is build/index.js.

Use with an MCP client

Claude Code

claude mcp add youtube-transcript -- node /absolute/path/to/mcp-youtube-transcript/build/index.js

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-youtube-transcript/build/index.js"]
    }
  }
}

Other clients that support stdio MCP servers (Cursor, Windsurf, Zed, etc.) use the same command and args.

Then ask your assistant something like: "Summarize https://www.youtube.com/watch?v=dQw4w9WgXcQ".

HTTP mode

Set MCP_TRANSPORT=http to expose a stateless Streamable HTTP endpoint instead of stdio.

MCP_TRANSPORT=http MCP_PORT=8000 npm start

Point an HTTP-capable client at http://localhost:8000/mcp.

Docker

docker build -t mcp-youtube-transcript .
docker run --rm -p 8000:8000 -e MCP_TRANSPORT=http mcp-youtube-transcript

Configuration

All configuration is via environment variables.

Development

npm run dev     # tsc --watch
npm test        # vitest
npm run build   # compile to build/

Source layout:

Limitations

• Transcripts come from the unofficial youtube-transcript package, which scrapes YouTube's caption data. YouTube can change its page structure at any time and break it.

• Videos without captions in the requested language return an error. Auto-generated captions usually work, but not always.

• Heavy use from one IP address may be rate limited or blocked by YouTube.

• HTTP mode is stateless and has no authentication. Do not expose it to the public internet without putting it behind a proxy that handles auth.

Contributing

Issues and pull requests are welcome. For anything larger than a small fix, open an issue first so we can talk it over. Please run npm test and npm run build before submitting.

License

MIT