mcp-youtube-transcript

YouTube Transcript MCP Server

[uv] [Python Application] [pre-commit] [GitHub License] [Dockerhub]

A Model Context Protocol (MCP) 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 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).

General Configuration (Standard MCP JSON)

Add this entry to your client's MCP configuration file (typically under mcpServers):

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jkawamoto/mcp-youtube-transcript",
        "mcp-youtube-transcript"
      ]
    }
  }
}

Claude Desktop

• GUI (Drag & Drop): Download the .mcpb bundle from the Releases page 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

Please refer to this tutorial for detailed installation instructions: YouTube Transcript Extension.

LM Studio

To configure this server for LM Studio, click the button below.

[Add MCP Server youtube-transcript to LM Studio]

Using Docker

A Docker image for this server is available on Docker Hub. 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:

• 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.

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):

{
  "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:

{
  "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, supply your API token:

{
  "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 for details.

3. Standard / Generic HTTP & HTTPS Proxies

Specify custom proxy endpoints via HTTP_PROXY / HTTPS_PROXY (or --http-proxy / --https-proxy):

{
  "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.

License

This application is licensed under the MIT License. See the LICENSE file for more details.