YouTube Transcript MCP Server

A Model Context Protocol (MCP) server that provides tools for fetching YouTube video transcripts and metadata using yt-dlp.

Features

• Get Transcript: Extract transcripts from YouTube videos in multiple languages
• Get Video Info: Retrieve video metadata including title, channel, and duration
• Rate Limiting: Built-in rate limiting to avoid YouTube API limits
• Fallback Support: Automatically falls back to available languages if English subtitles aren't available
• Multiple URL Formats: Supports both youtube.com/watch?v=... and youtu.be/... formats

Prerequisites

• Go 1.23 or later
• yt-dlp installed and available in PATH

Installing yt-dlp

# macOS (via Homebrew)
brew install yt-dlp

# Linux (via pip)
pip install yt-dlp

# Or download from releases: https://github.com/yt-dlp/yt-dlp/releases

Installation

# Clone the repository
git clone https://github.com/yourusername/youtube-transcript-mcp.git
cd youtube-transcript-mcp

# Install dependencies
go mod tidy

# Build the server
go build -o youtube-transcript-mcp

Usage

As MCP Server

This server implements the Model Context Protocol (MCP) and can be used with any MCP-compatible client.

Claude Code

claude mcp add youtube-transcript --scope user /path/to/youtube-transcript-mcp

Claude Desktop Configuration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "/path/to/youtube-transcript-mcp"
    }
  }
}

Available Tools

get_transcript

Fetches the transcript from a YouTube video URL.

Parameters:

• url (string, required): YouTube video URL (e.g., https://youtube.com/watch?v=dQw4w9WgXcQ)

Returns: String containing the full transcript text

get_video_info

Retrieves metadata about a YouTube video.

Parameters:

• url (string, required): YouTube video URL

Returns: JSON object with:

• title: Video title
• channel: Channel name
• duration: Video duration (formatted)
• url: Original URL

Command Line Usage

You can also run the server directly:

./youtube-transcript-mcp

The server will listen for MCP protocol messages on stdin/stdout.

API Examples

Getting a Transcript

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_transcript",
    "arguments": {
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    }
  }
}

Getting Video Info

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_video_info",
    "arguments": {
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    }
  }
}

Development

Running Tests

go test -v

Test Coverage

go test -cover

Building for Different Platforms

# Linux
GOOS=linux GOARCH=amd64 go build -o youtube-transcript-mcp-linux

# Windows
GOOS=windows GOARCH=amd64 go build -o youtube-transcript-mcp-windows.exe

# macOS ARM64
GOOS=darwin GOARCH=arm64 go build -o youtube-transcript-mcp-macos-arm64

Rate Limiting

The server implements automatic rate limiting with random delays between requests (1.5-3 seconds) to avoid hitting YouTube's rate limits. This is especially important when processing multiple videos.

Error Handling

The server handles various error conditions:

• Invalid YouTube URLs
• Videos without available transcripts
• Network connectivity issues
• yt-dlp execution errors

Dependencies

• mcp-go: MCP protocol implementation for Go
• soup: HTML parsing for metadata extraction
• yt-dlp: YouTube content extraction tool

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• yt-dlp for the excellent YouTube extraction capabilities
• MCP for the protocol specification
• mark3labs/mcp-go for the Go MCP implementation

Troubleshooting

Common Issues

1. "yt-dlp not found": Ensure yt-dlp is installed and in your PATH
2. Rate limiting errors: The server includes built-in delays, but you may need to use a proxy if you get IP banned
3. No transcript available: Some videos don't have transcripts - the server will return an appropriate error
4. Permission errors: Ensure the binary has execute permissions (chmod +x youtube-transcript-mcp)

Debug Mode

Set the LOG_LEVEL environment variable to enable debug logging:

LOG_LEVEL=debug ./youtube-transcript-mcp