# 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`](https://docs.astral.sh/uv/getting-started/installation/), a tool that installs Python and the dependencies for you
- [Claude Code](https://claude.com/claude-code) or [Claude Desktop](https://claude.ai/download) (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.

## 1. Download it

```bash
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

```bash
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

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

Check that it was added:

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

```json
{
  "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](https://www.webshare.io/) 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

```bash
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](https://github.com/modelcontextprotocol/python-sdk) 2.3 and [`youtube-transcript-api`](https://github.com/jdepoix/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](LICENSE).