youtube-mcp

<!-- mcp-name: com.transcriptout/youtube-transcript-and-youtube-search -->

<p align="center">
  <a href="https://transcriptout.com">
    <img src="public/brand/logo-512.png" width="120" height="120" alt="TranscriptOut" />
  </a>
</p>

<h1 align="center">YouTube Transcript &amp; Search MCP Server</h1>

<p align="center">
  <b>Let your AI agent read YouTube.</b><br/>
  Transcripts in five formats, native video and channel search, channel and playlist listings,
  and background jobs that deliver up to 4,000 transcripts at a time. 14 tools behind one hosted
  endpoint. Nothing runs on your machine.
</p>

<p align="center">
  <a href="https://cursor.com/en/install-mcp?name=transcriptout&config=eyJ1cmwiOiJodHRwczovL2FwaS50cmFuc2NyaXB0b3V0LmNvbS9tY3AifQ=="><img alt="Install in Cursor" src="https://img.shields.io/badge/Cursor-Install_MCP-000000?style=for-the-badge&logo=cursor&logoColor=white"/></a>
  <a href="https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22transcriptout%22%2C%22url%22%3A%22https%3A%2F%2Fapi.transcriptout.com%2Fmcp%22%7D"><img alt="Install in VS Code" src="https://img.shields.io/badge/VS_Code-Install_MCP-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white"/></a>
</p>

<p align="center">
  <a href="https://transcriptout.com"><img src="https://img.shields.io/badge/Website-transcriptout.com-FF3B00?style=for-the-badge" alt="Website"/></a>
  <a href="https://transcriptout.com/docs"><img src="https://img.shields.io/badge/Docs-API_Reference-06B6D4?style=for-the-badge&logo=readthedocs&logoColor=white" alt="Docs"/></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-4CAF50?style=for-the-badge" alt="MIT License"/></a>
</p>

<p align="center">
  <a href="#-why">Why</a> ·
  <a href="#-quick-start">Quick start</a> ·
  <a href="#-the-14-tools">Tools</a> ·
  <a href="#-install-in-your-client">Install</a> ·
  <a href="#-recipes">Recipes</a> ·
  <a href="#-pricing-and-limits">Pricing</a> ·
  <a href="#-when-a-call-fails">Errors</a>
</p>

---

## 🎬 Why

Everyone who works with an agent has run this exchange at least once.

```txt
You:   Summarize this. https://www.youtube.com/watch?v=kCc8FmEb1nY
Agent: I'm not able to watch videos. If you paste the transcript here, I'll gladly help!
```

The transcript is precisely the thing the agent cannot get on its own. With this server
connected, the same message simply resolves.

```txt
You:   Summarize this. https://www.youtube.com/watch?v=kCc8FmEb1nY
Agent: → get_transcript(video="kCc8FmEb1nY", video_metadata=true)      1 credit

       That's "Let's build GPT: from scratch, in code, spelled out" by Andrej
       Karpathy, 1:56:20. He starts from an empty file and a bigram model,
       derives self-attention step by step, and ends with a working GPT that...
```

Reading one video is rarely where the job ends. Here is how the three ways of getting YouTube
data into an agent actually compare.

|                          | This server | Local yt-dlp / scraper MCP | Google YouTube Data API |
| ------------------------ | ----------- | -------------------------- | ----------------------- |
| Transcripts              | ✅ any public video, 5 formats | ⚠️ blocked on datacenter IPs, breaks when YouTube changes markup | ❌ not served at all |
| Setup                    | ✅ a URL and an API key | ❌ local install, binaries to keep alive | ❌ Cloud project, OAuth consent screens |
| YouTube search           | ✅ native, 1 credit per page | ❌ | ⚠️ 100 quota units per search |
| Channels & playlists     | ✅ 100 videos/page, or 500 bare IDs | ❌ one video at a time | ⚠️ quota-metered per item |
| Bulk transcripts         | ✅ 4,000 per background job | ❌ | ❌ |
| RAG-ready chunking       | ✅ 20-5,000 chars, word-level timestamps | ❌ | ❌ |
| When YouTube changes     | ✅ fixed server-side, nothing to update | ❌ you patch and redeploy | ✅ |
| Failed calls             | ✅ credits refund themselves | ❌ your retry logic | ⚠️ quota spent anyway |

---

## ⚡ Quick start

**1. Get an API key.** Sign up at [transcriptout.com](https://transcriptout.com) and create a key
in the [dashboard](https://transcriptout.com/dashboard). New accounts receive 100 free credits and
no card is asked. Keys start with `sk_` and are shown once.

**2. Point your client at the server.** It speaks streamable HTTP and authenticates with one
Bearer header.

```json
{
  "mcpServers": {
    "transcriptout": {
      "url": "https://api.transcriptout.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

One-click buttons for Cursor and VS Code sit at the top of this page. Exact snippets for the rest
live under [Install in your client](#-install-in-your-client).

**3. Paste a link.**

```txt
Summarize this talk and pull the three strongest quotes.
https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

The agent picks `get_transcript` on its own, reads the timed text and answers from it. Every
response carries an `X-Credits-Remaining` header, so the budget stays in view the whole session.

---

## 🧰 The 14 tools

All 14 tools are exposed automatically once you connect. **Most calls cost 1 credit.** Credits
are refunded automatically when a call fails before reaching YouTube (validation errors, rate
limits, our own capacity), so you pay for answers, not for failures. A definitive "this video has no
captions" is an answer and is billed like one.

### 1. `get_transcript` · 1 credit

Fetch the transcript of any YouTube video. `format=text` (default) returns plain readable text,
cheapest for a model to reason over, and `format=json` returns timed segments.

| Parameter        | Type    | Default      | Description                                                    |
| ---------------- | ------- | ------------ | -------------------------------------------------------------- |
| `video`          | string  | **required** | YouTube URL (full or short) or 11-char video ID                |
| `lang`           | string  | `"en"`       | Language code of the track (`en`, `de`, ...)                   |
| `format`         | string  | `"text"`     | `"text"` (plain text), `"json"` (segments with `start`/`duration` in seconds), `"srt"`/`"vtt"` (subtitle file body), `"srv3"` (raw YouTube XML) |
| `kind`           | string  | auto-detect  | `"manual"` or `"auto"`. Left out, a manual track wins and auto is the fallback |
| `segment`        | integer | see below    | Max characters per segment. 500-1500 makes RAG-ready chunks    |
| `video_metadata` | boolean | `false`      | Add title, channel, duration and views in the SAME call, same 1 credit |

Left out, `segment` cuts auto-generated tracks into ~180-character segments and returns manual
tracks exactly as their author broke them. Pass it whenever you need one size regardless of which
track answers.

**Example output (`format=json`):**

```json
{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "kind": "manual",
  "transcript": [
    { "text": "Never gonna give you up", "start": 18.0, "duration": 4.12 },
    { "text": "Never gonna let you down", "start": 22.12, "duration": 3.85 }
  ]
}
```

> `srt` and `vtt` come back as complete subtitle file bodies, ready to be written to disk by the
> agent. `srv3` is the raw source XML and does not combine with `segment`.

### 2. `get_video_info` · 1 credit

Metadata for one video (title, channel, duration, views, thumbnails) plus the list of available
transcript languages, WITHOUT downloading the subtitles.

| Parameter | Type   | Default      | Description                |
| --------- | ------ | ------------ | -------------------------- |
| `id`      | string | **required** | YouTube video ID or URL    |

> **Credit hygiene:** if you are going to fetch the transcript anyway, call `get_transcript` with
> `video_metadata=true` instead. It returns both for one credit where these are two calls and two.

### 3. `search_youtube` · 1 credit/page

Search YouTube for videos or channels. Paginate with `next_page_token`. `has_more` tells you
whether another page exists.

| Parameter         | Type    | Default   | Description                          |
| ----------------- | ------- | --------- | ------------------------------------ |
| `q`               | string  | required* | Search query (*unless paginating)    |
| `type`            | string  | `"video"` | `"video"` or `"channel"`             |
| `limit`           | integer | `20`      | Results per page, 1-50               |
| `next_page_token` | string  |           | Token from a previous result         |

### 4. `list_channel_videos` · 1 credit/page

List videos from a channel's Videos tab, newest first. Accepts an `@handle`, a channel name, a
`UC...` channel ID or a channel URL.

| Parameter         | Type    | Default   | Description                                        |
| ----------------- | ------- | --------- | -------------------------------------------------- |
| `name`            | string  | required* | `@handle`, channel name, `UC...` ID or URL         |
| `limit`           | integer | `100`     | Page size, up to 500 with `ids_only`               |
| `ids_only`        | boolean | `false`   | Return just `video_ids[]`, up to 500 per page      |
| `next_page_token` | string  |           | Token from a previous result                       |

> `ids_only=true` is the cheap way to feed `submit_transcripts_job`.

### 5. `search_channel_videos` · 1 credit/page

Search inside one channel using YouTube's native relevance search. A result whose title lacks the
query word is normal. Results are ranked by relevance, not by substring.

| Parameter         | Type    | Default   | Description                          |
| ----------------- | ------- | --------- | ------------------------------------ |
| `name`            | string  | required  | `@handle`, channel name, `UC...` ID or URL |
| `q`               | string  | required  | Query to search within the channel   |
| `limit`           | integer | `30`      | Results