YouTube Transcript MCP Server

<div align="center"> <img src="assets/logo.png" alt="YouTube Transcript MCP Logo" width="200"/> # YouTube Transcript Remote MCP Server The **first remote** Model Context Protocol (MCP) server that enables Claude AI to extract transcripts from YouTube videos. This server offers zero-setup access for users on any platform including mobile devices. </div> [](https://deploy.workers.cloudflare.com/?url=https://github.com/ergut/youtube-transcript-mcp) ## 🌟 Features - **Zero Local Setup**: No installation required - works directly from the cloud - **Universal Access**: Works on desktop, mobile, and web versions of Claude - **Smart Caching**: Efficient caching system using Cloudflare KV for fast responses - **Multi-language Support**: Extract transcripts in different languages - **Error Handling**: Robust error handling with user-friendly messages - **Analytics**: Built-in request tracking and usage analytics - **URL Flexibility**: Handles all YouTube URL formats (youtube.com, youtu.be, m.youtube.com, etc.) ## 🚀 Quick Start ### Option 1: Use Our Hosted Server (Recommended) The easiest way to get started - just add our public server to your Claude Desktop: #### For Claude Desktop Users 1. **Open Claude Desktop Settings** - Click on "Claude" in the menu bar → "Settings" - Navigate to "Developer" tab - Click "Edit Config" 2. **Add the MCP Server Configuration** Add this to your `claude_desktop_config.json`: ```json { "mcpServers": { "youtube-transcript": { "command": "npx", "args": [ "mcp-remote", "https://youtube-transcript-mcp.ergut.workers.dev/sse" ] } } } ``` 3. **Restart Claude Desktop** After saving the config file, restart Claude Desktop to load the server. 4. **Verify Installation** Look for the tools icon (🔧) in the chat interface. You should see the `get_transcript` tool available. ### Option 2: Deploy Your Own Want to run your own instance? Deploy to Cloudflare Workers in one click: [](https://deploy.workers.cloudflare.com/?url=https://github.com/ergut/youtube-transcript-mcp) Or manually: ```bash git clone https://github.com/ergut/youtube-transcript-mcp cd youtube-transcript-mcp npm install npm run deploy ``` ### For Other MCP Clients The server supports the standard MCP protocol and can be used with any compatible client: - **Public Server URL**: `https://youtube-transcript-mcp.ergut.workers.dev/sse` - **Transport**: Server-Sent Events (SSE) or HTTP - **Authentication**: None required (public server) ## 📖 Usage Examples ### Basic Transcript Extraction ``` Extract the transcript from this YouTube video: https://www.youtube.com/watch?v=dQw4w9WgXcQ ``` ### Multi-language Support ``` Can you get the transcript of this video in Turkish: https://youtu.be/VIDEO_ID ``` ``` Extract the Spanish transcript from: https://www.youtube.com/watch?v=VIDEO_ID ``` ### Supported URL Formats The server automatically handles all YouTube URL formats: - `https://www.youtube.com/watch?v=VIDEO_ID` - `https://youtu.be/VIDEO_ID` - `https://m.youtube.com/watch?v=VIDEO_ID` - `https://www.youtube.com/live/VIDEO_ID` - `https://www.youtube.com/embed/VIDEO_ID` - `https://www.youtube.com/shorts/VIDEO_ID` - International domains (`youtube.co.uk`, `youtube.de`, etc.) All tracking parameters (like `?si=`, `&t=`, etc.) are automatically removed. ## 🛠 Available Tools ### `get_transcript` Extracts the transcript from a YouTube video URL. **Parameters:** - `url` (required): YouTube video URL in any format - `language` (optional): Language code for the transcript (e.g., 'en', 'es', 'fr'). Defaults to 'en'. **Example Usage:** ```json { "name": "get_transcript", "arguments": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "language": "en" } } ``` ## 🔧 Advanced Configuration ### Debug Logging To enable detailed logging for troubleshooting: ```json { "mcpServers": { "youtube-transcript": { "command": "npx", "args": [ "mcp-remote", "https://youtube-transcript-mcp.ergut.workers.dev/sse", "--debug" ] } } } ``` Debug logs will be created in `~/.mcp-auth/{server_hash}_debug.log`. ### HTTP Transport Only To force HTTP transport instead of SSE: ```json { "mcpServers": { "youtube-transcript": { "command": "npx", "args": [ "mcp-remote", "https://youtube-transcript-mcp.ergut.workers.dev/mcp", "--transport", "http-only" ] } } } ``` ## 📊 Server Information - **Hosting**: Cloudflare Workers - **Caching**: Cloudflare KV with 7-day cache for successful transcripts - **Rate Limiting**: Built-in retry logic with exponential backoff - **Uptime**: 99.9%+ availability through Cloudflare's global network - **Response Time**: Typically <3 seconds for cached content, <10 seconds for new requests ## 🚨 Error Handling The server provides clear error messages for common issues: - **"Invalid YouTube URL provided"**: The URL format is not recognized - **"No transcript available for this video"**: Video has no captions/transcript - **"Video not found or private"**: Video is private, deleted, or doesn't exist - **"Service temporarily busy, try again in a few minutes"**: Rate limiting from YouTube - **"Transcripts are disabled for this video"**: Creator has disabled captions ## 🌍 Language Support The server supports any language that YouTube provides transcripts for. Common language codes: - `en` - English (default) - `tr` - Turkish - `es` - Spanish - `fr` - French - `de` - German - `it` - Italian - `pt` - Portuguese - `ja` - Japanese - `ko` - Korean - `zh` - Chinese ## 🔒 Privacy & Security - **No Authentication Required**: Public server for ease of use - **No Data Storage**: Transcripts are cached temporarily for performance only - **No Personal Information**: Only YouTube video IDs and transcripts are processed - **HTTPS Only**: All communications are encrypted - **CORS Enabled**: Supports web-based MCP clients ## 🚀 API Endpoints For developers who want to integrate directly: ### HTTP POST `/mcp` Standard MCP JSON-RPC endpoint for direct integration. ### Server-Sent Events `/sse` MCP SSE transport endpoint for real-time communication. ### Info `/` Server information and status endpoint. **Example Direct API Call:** ```bash curl -X POST https://youtube-transcript-mcp.ergut.workers.dev/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_transcript", "arguments": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "language": "en" } } }' ``` ## 🐛 Troubleshooting ### Common Issues 1. **"Connection Error" in Claude Desktop** - Ensure you have the latest Claude Desktop version - Check that `mcp-remote` is properly configured - Try adding `--debug` flag to see detailed logs 2. **"Could not attach to MCP server"** - Verify your internet connection - Check the server URL is correct - Restart Claude Desktop after config changes 3. **No transcript returned** - Verify the YouTube URL is valid and accessible - Check if the video has captions enabled - Try a different language code if available ### Getting Help - **Check logs**: Look in `~/.mcp-auth/` for debug logs - **Test direct connection**: Use `npx -p mcp-remote@latest mcp-remote-client https://youtube-transcript-mcp.ergut.workers.dev/sse` - **Verify server status**: Visit `https://youtube-transcript-mcp.ergut.workers.dev/` - **Open an issue**: [GitHub Issues](https://github.com/ergut/youtube-transcript-mcp/issues) ## 🤝 Contributing This is an open-source project. Contributions are welcome! - **Report Issues**: Found a bug? Please [open an issue](https://github.com/ergut/youtube-transcript-mcp/issues) - **Feature Requests**: Have ideas for improvements? Let us know! - **Code Contributions**: PRs welcome for enhancements ### Development Setup ```bash git clone https://github.com/ergut/youtube-transcript-mcp cd youtube-transcript-mcp npm install npm run dev ``` ## 📜 License This project is open source and available under the [MIT License](LICENSE). ## 🙏 Acknowledgments - Built with the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic - Hosted on [Cloudflare Workers](https://workers.cloudflare.com/) - Uses the [youtube-transcript](https://www.npmjs.com/package/youtube-transcript) library - Inspired by the MCP community and existing local transcript servers --- **Ready to supercharge Claude with YouTube transcript extraction?** Add this server to your Claude Desktop configuration and start extracting transcripts from any YouTube video instantly! 🎉