YouTube Transcript MCP Server
by jkawamoto
README.md
# YouTube Transcript MCP Server
[](https://github.com/astral-sh/uv)
[](https://github.com/jkawamoto/mcp-youtube-transcript/actions/workflows/python-app.yaml)
[](https://github.com/pre-commit/pre-commit)
[](https://github.com/jkawamoto/mcp-youtube-transcript/blob/main/LICENSE)
[](https://hub.docker.com/mcp/server/youtube_transcript)
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server
that fetches transcripts and metadata from YouTube videos directly into your LLM workflows.
Designed specifically for AI agents, it seamlessly handles long-form videos through automatic pagination
and provides robust proxy support to circumvent YouTube rate limits and IP bans.
## Key Features
- **Rich Transcript Retrieval**: Fetch raw text, timestamped segments, and video metadata in multiple languages.
- **Smart Chunking & Pagination**: Automatically chunks long transcripts (default: 50,000 characters) to prevent context
window overflow, letting models page through hours of video effortlessly.
- **Resilient Proxy Support**: Built-in support for residential proxies (Webshare, ScrapingAnt)
and standard HTTP/HTTPS proxies to prevent IP blocks.
- **Universal Compatibility**: Works with Claude Desktop, Cursor, LM Studio, Goose, and any standard MCP client.
## Quick Start & Installation
> [!NOTE]
> You'll need [`uv`](https://docs.astral.sh/uv) installed on your system to use `uvx` command.
This server communicates via standard `stdio`.
Most MCP clients can run it directly using `uvx` (part of [Astral `uv`](https://github.com/astral-sh/uv)).
### General Configuration (Standard MCP JSON)
Add this entry to your client's MCP configuration file (typically under `mcpServers`):
```json
{
"mcpServers": {
"youtube-transcript": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/jkawamoto/mcp-youtube-transcript",
"mcp-youtube-transcript"
]
}
}
}
```
<details>
<summary><strong>Client-Specific Setup Guides (Click to expand)</strong></summary>
#### Claude Desktop
- **GUI (Drag & Drop)**: Download the `.mcpb` bundle
from the [Releases page](https://github.com/jkawamoto/mcp-youtube-transcript/releases)
and drop it into your Claude Desktop Settings.
- **Manual Config**: Add the JSON above to `claude_desktop_config.json` (restart Claude Desktop after saving):
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
#### Cursor
1. Go to **Cursor Settings** > **Features** > **MCP Servers**.
2. Click **+ Add New MCP Server**.
3. Name: `youtube-transcript`, Type: `command`.
4. Command: `uvx --from git+https://github.com/jkawamoto/mcp-youtube-transcript mcp-youtube-transcript`
#### [Goose](https://block.github.io/goose/)
Please refer to this tutorial for detailed installation instructions:
[YouTube Transcript Extension](https://block.github.io/goose/docs/mcp/youtube-transcript-mcp).
#### [LM Studio](https://lmstudio.ai/)
To configure this server for LM Studio, click the button below.
[](https://lmstudio.ai/install-mcp?name=youtube-transcript&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXQraHR0cHM6Ly9naXRodWIuY29tL2prYXdhbW90by9tY3AteW91dHViZS10cmFuc2NyaXB0IiwibWNwLXlvdXR1YmUtdHJhbnNjcmlwdCJdfQ%3D%3D)
</details>
### Using Docker
A Docker image for this server is available on [Docker Hub](https://hub.docker.com/mcp/server/youtube_transcript/).
Please refer to the Docker Hub page for detailed usage instructions and documentation.
## Available Tools
The server registers the following MCP tools for LLM agents:
| Tool | Description |
| :--- | :--- |
| `get_transcript` | Retrieves the plain-text transcript for a YouTube video URL. |
| `get_timed_transcript` | Retrieves transcript segments with start times and durations. |
| `get_available_languages` | Lists all available transcript languages (manual & auto-generated). |
| `get_video_info` | Fetches video metadata such as title and channel information. |
<details>
<summary><strong>Tool Parameters & Schema</strong></summary>
- **`get_transcript`**
- `url` (*string, required*): Full YouTube video URL.
- `lang` (*string, optional*): Preferred language code (defaults to `"en"`).
- `next_cursor` (*integer, optional*): Cursor to fetch the next chunk for long videos.
- **`get_timed_transcript`**
- `url` (*string, required*): Full YouTube video URL.
- `lang` (*string, optional*): Preferred language code (defaults to `"en"`).
- `next_cursor` (*integer, optional*): Cursor to fetch the next chunk.
- **`get_available_languages`**
- `url` (*string, required*): Full YouTube video URL.
- **`get_video_info`**
- `url` (*string, required*): Full YouTube video URL.
</details>
## Advanced Configuration
### Handling Long Videos (Pagination)
Long videos (e.g., lectures, conferences, podcast episodes) can quickly exceed LLM token context limits.
By default, transcripts exceeding **50,000 characters** are chunked. When a response is split,
a `next_cursor` is provided so the LLM agent can autonomously query the rest.
To customize the chunk character limit, supply `--response-limit`.
To disable pagination and fetch the entire transcript at once, set `--response-limit` to a negative value (e.g., `-1`):
```json
{
"mcpServers": {
"youtube-transcript": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/jkawamoto/mcp-youtube-transcript",
"mcp-youtube-transcript",
"--response-limit",
"15000"
]
}
}
}
```
### Avoiding IP Bans (Proxy Setup)
YouTube aggressively blocks automated transcript requests from cloud providers and data center IPs.
Using residential or rotating proxies ensures uninterrupted access.
#### 1. Webshare Residential Proxy
Set credentials via environment variables or command-line flags:
```json
{
"mcpServers": {
"youtube-transcript": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/jkawamoto/mcp-youtube-transcript",
"mcp-youtube-transcript"
],
"env": {
"WEBSHARE_PROXY_USERNAME": "your_username",
"WEBSHARE_PROXY_PASSWORD": "your_password"
}
}
}
}
```
*(CLI equivalents: `--webshare-proxy-username` and `--webshare-proxy-password`)*
#### 2. ScrapingAnt
If using [ScrapingAnt](https://scrapingant.com/?ref=mdk4y2q), supply your API token:
```json
{
"mcpServers": {
"youtube-transcript": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/jkawamoto/mcp-youtube-transcript",
"mcp-youtube-transcript"
],
"env": {
"SCRAPINGANT_API_TOKEN": "your_api_token"
}
}
}
}
```
*(CLI equivalent: `--scrapingant-api-token`)*
Accessing YouTube requires a paid ScrapingAnt Web Scraping API subscription.
YouTube access requires residential proxies, which consume more ScrapingAnt credits than standard proxy requests.
See [the ScrapingAnt credit cost documentation](https://docs.scrapingant.com/credits-cost) for details.
#### 3. Standard / Generic HTTP & HTTPS Proxies
Specify custom proxy endpoints via `HTTP_PROXY` / `HTTPS_PROXY` (or `--http-proxy` / `--https-proxy`):
```json
{
"mcpServers": {
"youtube-transcript": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/jkawamoto/mcp-youtube-transcript",
"mcp-youtube-transcript"
],
"env": {
"HTTPS_PROXY": "http://username:password@proxy.example.com:8080"
}
}
}
}
```
For more details, please visit:
[Working around IP bans - YouTube Transcript API](https://github.com/jdepoix/youtube-transcript-api?tab=readme-ov-file#working-around-ip-bans-requestblocked-or-ipblocked-exception).
## License
This application is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
TDQS
A3.5/5.0
Scored across 4 tools
Disambiguation4/5
Each tool targets a distinct output type, though get_transcript and get_timed_transcript overlap heavily in purpose and are only separated by the presence of timestamps. get_available_languages and get_video_info are clearly distinct from transcript retrieval.
Naming Consistency5/5
All four tools follow a consistent get_noun snake_case pattern, making the set highly predictable and readable.
Tool Count5/5
Four tightly scoped tools is appropriate for a focused YouTube transcript server. Each tool earns its place without extraneous surface area.
Completeness4/5
Core needs—transcript text, timestamped transcript, language availability, and video metadata—are covered. Minor gaps like transcript translation or search within a transcript are not present but are not essential to the stated purpose.
Maintenance
ActivityActive
ResponsivenessSlow