youtube-transcript-mcp

An MCP server that lets an AI assistant read a YouTube video's transcript.

You give the assistant a YouTube link. It calls one tool, get_transcript, and gets the captions back with a start time on every line:

[0:02] tech professionals, and in this video,
[0:04] I'm going to share with you exactly what
[0:06] works, what clients are paying for right

The timestamps let the assistant (and you) point at the exact moment something was said.

New to MCP? It stands for Model Context Protocol. It is a standard way to give an AI assistant a small program it can call, the way a charger standard lets one cable fit many devices. This server is one such program. It runs on your own computer.

What you need

• A computer running macOS, Linux or Windows

• uv, a tool that installs Python and the dependencies for you

• Claude Code or Claude Desktop (any assistant that supports MCP servers over stdio will also work)

• Python 3.11 or newer. If you don't have it, uv will fetch it.

Related MCP server: YouTube Transcript MCP Server

1. Download it

git clone https://github.com/noelogbuagu/youtube-transcript-mcp.git
cd youtube-transcript-mcp
pwd

Copy the folder path that pwd prints. You need it in the next step. On Windows PowerShell, use Get-Location instead.

2. Check that it works

uv run client.py

The first run downloads the dependencies. You should see a video id, a character count and the first few lines of a transcript. If you do, the server works.

3. Add it to your assistant

Replace /full/path/to/youtube-transcript-mcp with the path you copied.

Claude Code

claude mcp add --transport stdio youtube-transcript -- uv --directory "/full/path/to/youtube-transcript-mcp" run server.py

Check that it was added:

claude mcp list

Then start claude and ask: "Get the transcript of https://www.youtube.com/watch?v=1HtydHmdhrQ and summarise the main point."

Claude Desktop

1. Open Settings > Developer > Edit Config. This opens claude_desktop_config.json.

2. Add the server under mcpServers:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "uv",
      "args": [
        "--directory",
        "/full/path/to/youtube-transcript-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

3. Quit Claude Desktop completely and open it again. The get_transcript tool should now appear in the tools list.

If Claude Desktop says it cannot find uv, replace "command": "uv" with the full path to it. Run which uv (macOS and Linux) or where uv (Windows) to get that path. Desktop apps often don't see the same PATH as your terminal.

Cursor and other editors

Any editor that can start an MCP server over stdio works with the same command: uv --directory "/full/path/to/youtube-transcript-mcp" run server.py.

Troubleshooting

• Error: Could not retrieve a transcript: the video may have no captions, or captions may be turned off by its owner. Try another video.

• Works in the terminal, fails after a while or from a cloud machine: YouTube blocks requests that come from many data-centre addresses. Running the server on your own computer is the reliable way. If you do hit blocks, the next section helps.

• The tool doesn't show up in Claude Desktop: the config file must be valid JSON (watch for missing commas), and you must fully quit and reopen the app.

Optional: use a proxy

If YouTube blocks your requests, you can route them through a Webshare proxy. Copy .env.example to .env and fill in:

WEBSHARE_USERNAME=
WEBSHARE_PASSWORD=

Leave them empty and the server connects directly. .env is ignored by git, so your credentials stay local.

Using it as a thinking partner

A transcript on its own is just text. What helped me was keeping a notebook next to it: a short note of what I'm trying to decide, and one small file per video with what I took from it. The notebook.example/ folder shows the shape: an aim.md, a card template, and a few rules for the assistant to follow in AGENTS.md. Copy it into its own folder and point your assistant at it.

Development

uv run --group dev pytest        # offline tests, no network needed
uv run client.py                 # live smoke test
uv run server.py --transport streamable-http   # serve over HTTP on 127.0.0.1:8050
uv run mcp dev server.py         # open the MCP Inspector

Project layout

youtube-transcript-mcp/
  server.py                         # entrypoint your assistant starts
  client.py                         # smoke test: starts the server and calls the tool
  notebook.example/                 # optional notes setup
  src/youtube_transcript_mcp/
    utils.py                        # video id parsing, [m:ss] formatting
    youtube/service.py              # fetches captions, optional proxy
    mcp/server.py                   # exposes get_transcript as an MCP tool
  tests/

Built on the MCP Python SDK 2.3 and youtube-transcript-api.

Not built yet

• Saving transcripts so a later chat can search what was already watched.

• Hosting the server so it works away from your computer.

License

MIT. See LICENSE.