{"_id":"@tanush-yadav/youtube-transcript-mcp","name":"@tanush-yadav/youtube-transcript-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@tanush-yadav/youtube-transcript-mcp","version":"1.0.0","description":"Model Context Protocol server for extracting YouTube video transcripts. Works with Claude Desktop and other MCP-compatible clients.","main":"index.js","type":"module","bin":{"yt-transcript-mcp":"index.js"},"scripts":{"start":"node index.js","test":"node test.js","prepublishOnly":"npm test"},"keywords":["mcp","youtube","transcript","modelcontextprotocol","claude","llm","ai","youtube-api","captions","subtitles","video-transcript","youtubei.js"],"author":{"name":"Tanush Yadav","email":"tanush@cintra.run"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/tanush-yadav/youtube-transcript-mcp.git"},"bugs":{"url":"https://github.com/tanush-yadav/youtube-transcript-mcp/issues"},"homepage":"https://github.com/tanush-yadav/youtube-transcript-mcp#readme","dependencies":{"@modelcontextprotocol/sdk":"^0.6.0","youtubei.js":"^15.0.1"},"engines":{"node":">=18.0.0"},"_id":"@tanush-yadav/youtube-transcript-mcp@1.0.0","gitHead":"a33aa234adc1ef5557a9078a48830beb5e79b787","_nodeVersion":"22.16.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-1QOFYx4fJ3BiGISal+WXw+jRvH3Oy89M+Bb7RrcXM3wJbXVpZ08SFhXvrmITfEISIeMtAYV8Ixu5pbUwqg8XUA==","shasum":"f8c0eedb7695652d53f6193caddc1d9461305cbe","tarball":"https://registry.npmjs.org/@tanush-yadav/youtube-transcript-mcp/-/youtube-transcript-mcp-1.0.0.tgz","fileCount":4,"unpackedSize":23301,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDtgkc9hZ4EYoTu3RaEQQJe+igus8XWdV+8KQEV6UMojAIhAMyZwBkEf7xVm1CfgStSvojPLZwdXMqUOgqomCcY0VjQ"}]},"_npmUser":{"name":"tanush-yadav","email":"tanush@cintra.run"},"directories":{},"maintainers":[{"name":"tanush-yadav","email":"tanush@cintra.run"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/youtube-transcript-mcp_1.0.0_1756890413954_0.6291213937881313"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-03T09:06:53.844Z","1.0.0":"2025-09-03T09:06:54.149Z","modified":"2025-09-03T09:06:54.448Z"},"maintainers":[{"name":"tanush-yadav","email":"tanush@cintra.run"}],"description":"Model Context Protocol server for extracting YouTube video transcripts. Works with Claude Desktop and other MCP-compatible clients.","homepage":"https://github.com/tanush-yadav/youtube-transcript-mcp#readme","keywords":["mcp","youtube","transcript","modelcontextprotocol","claude","llm","ai","youtube-api","captions","subtitles","video-transcript","youtubei.js"],"repository":{"type":"git","url":"git+https://github.com/tanush-yadav/youtube-transcript-mcp.git"},"author":{"name":"Tanush Yadav","email":"tanush@cintra.run"},"bugs":{"url":"https://github.com/tanush-yadav/youtube-transcript-mcp/issues"},"license":"MIT","readme":"# YouTube Transcript MCP Server\n\n[![npm version](https://badge.fury.io/js/youtube-transcript-mcp.svg)](https://www.npmjs.com/package/youtube-transcript-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/node/v/youtube-transcript-mcp.svg)](https://nodejs.org)\n\nA Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to extract transcripts from YouTube videos. Built with the reliable `youtubei.js` library, this server provides seamless transcript extraction with support for timestamps, metadata, and file exports.\n\n## ✨ Features\n\n- 🎥 **Extract transcripts** from any YouTube video with captions\n- ⏱️ **Timestamp support** - Get transcripts with or without timestamps\n- 📊 **Rich metadata** - Word count, duration, segment count, and more\n- 💾 **Export to files** - Save transcripts as text files\n- 🔧 **Flexible input** - Accepts full URLs, short URLs, or just video IDs\n- ⚡ **High reliability** - Uses YouTube's internal API via youtubei.js\n- 🚀 **No API key required** - Works out of the box\n- 🛡️ **Error handling** - Clear, actionable error messages\n\n## 📦 Installation\n\n### As an MCP Server for Claude Desktop\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/youtube-transcript-mcp.git\ncd youtube-transcript-mcp\n\n# Install dependencies\nnpm install\n```\n\n### As an npm Package\n\n```bash\nnpm install youtube-transcript-mcp\n```\n\nOr using yarn:\n\n```bash\nyarn add youtube-transcript-mcp\n```\n\n## 🚀 Quick Start\n\n### Configuration for Claude Desktop\n\nAdd the server to your Claude Desktop configuration:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n**Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"youtube-transcript\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/youtube-transcript-mcp/index.js\"]\n    }\n  }\n}\n```\n\nOr if installed globally via npm:\n\n```json\n{\n  \"mcpServers\": {\n    \"youtube-transcript\": {\n      \"command\": \"npx\",\n      \"args\": [\"youtube-transcript-mcp\"]\n    }\n  }\n}\n```\n\n## 🛠️ Available Tools\n\n### 1. `get_transcript`\n\nExtract transcript from a YouTube video with optional timestamps.\n\n**Parameters:**\n\n- `url` (string, required): YouTube video URL or video ID\n- `include_timestamps` (boolean, optional): Include timestamps in output (default: false)\n\n**Example Request:**\n\n```javascript\n{\n  \"name\": \"get_transcript\",\n  \"arguments\": {\n    \"url\": \"https://youtube.com/watch?v=dQw4w9WgXcQ\",\n    \"include_timestamps\": true\n  }\n}\n```\n\n**Example Output with timestamps:**\n\n```\n[00:00] We're no strangers to love\n[00:04] You know the rules and so do I\n[00:08] A full commitment's what I'm thinking of\n```\n\n### 2. `get_transcript_with_metadata`\n\nExtract transcript along with comprehensive metadata.\n\n**Parameters:**\n\n- `url` (string, required): YouTube video URL or video ID\n\n**Example Response:**\n\n```json\n{\n  \"metadata\": {\n    \"video_id\": \"dQw4w9WgXcQ\",\n    \"video_url\": \"https://youtube.com/watch?v=dQw4w9WgXcQ\",\n    \"word_count\": 251,\n    \"segment_count\": 42,\n    \"duration\": \"3:32\",\n    \"duration_seconds\": 212,\n    \"language\": \"en\",\n    \"is_auto_generated\": false\n  },\n  \"transcript\": \"Never gonna give you up...\",\n  \"full_transcript_length\": 1234\n}\n```\n\n### 3. `save_transcript`\n\nSave transcript to text file(s) on the local filesystem.\n\n**Parameters:**\n\n- `url` (string, required): YouTube video URL or video ID\n- `filename` (string, required): Base filename (without extension)\n- `with_timestamps` (boolean, optional): Save version with timestamps (default: true)\n\n**Example:**\n\n```javascript\n{\n  \"name\": \"save_transcript\",\n  \"arguments\": {\n    \"url\": \"https://youtu.be/dQw4w9WgXcQ\",\n    \"filename\": \"rickroll_transcript\",\n    \"with_timestamps\": true\n  }\n}\n```\n\nCreates files:\n\n- `rickroll_transcript_clean.txt` - Plain text transcript\n- `rickroll_transcript_with_timestamps.txt` - Transcript with timestamps (if enabled)\n\n## 💻 Programmatic Usage\n\n### As an MCP Client\n\n```javascript\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js'\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'\n\n// Initialize transport\nconst transport = new StdioClientTransport({\n  command: 'node',\n  args: ['/path/to/youtube-transcript-mcp/index.js'],\n})\n\n// Create client\nconst client = new Client({\n  name: 'youtube-transcript-client',\n  version: '1.0.0',\n})\n\n// Connect and use\nawait client.connect(transport)\n\n// Get transcript with timestamps\nconst result = await client.callTool({\n  name: 'get_transcript',\n  arguments: {\n    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',\n    include_timestamps: true,\n  },\n})\n\nconsole.log(result.content[0].text)\n```\n\n### Direct Module Usage\n\n```javascript\n// Coming soon: Direct module import support\nimport { YouTubeTranscriptExtractor } from 'youtube-transcript-mcp'\n\nconst extractor = new YouTubeTranscriptExtractor()\nconst transcript = await extractor.getTranscript('dQw4w9WgXcQ')\nconsole.log(transcript)\n```\n\n## 🌐 Supported URL Formats\n\nThe server accepts various YouTube URL formats:\n\n- ✅ Standard: `https://www.youtube.com/watch?v=VIDEO_ID`\n- ✅ Short: `https://youtu.be/VIDEO_ID`\n- ✅ Embed: `https://www.youtube.com/embed/VIDEO_ID`\n- ✅ Mobile: `https://m.youtube.com/watch?v=VIDEO_ID`\n- ✅ Shorts: `https://www.youtube.com/shorts/VIDEO_ID`\n- ✅ With timestamps: `https://youtube.com/watch?v=VIDEO_ID&t=123`\n- ✅ With playlist: `https://youtube.com/watch?v=VIDEO_ID&list=PLAYLIST_ID`\n- ✅ Just video ID: `dQw4w9WgXcQ`\n\n## 📝 Usage Examples with Claude\n\nOnce configured, you can ask Claude:\n\n```\n\"Get the transcript from https://www.youtube.com/watch?v=dQw4w9WgXcQ\"\n\n\"Extract the YouTube transcript with timestamps from video ID abc123\"\n\n\"Save the transcript from this video to a file: [URL]\"\n\n\"Get detailed metadata and transcript from: [URL]\"\n\n\"Summarize this YouTube video: [URL]\" (Claude will fetch and summarize)\n```\n\n## 🔧 Development\n\n### Running Tests\n\n```bash\nnpm test\n```\n\n### Building from Source\n\n```bash\ngit clone https://github.com/yourusername/youtube-transcript-mcp.git\ncd youtube-transcript-mcp\nnpm install\nnpm run build\n```\n\n### Development Mode\n\n```bash\nnpm run dev\n```\n\n### Testing the MCP Server\n\nCreate a test file `test-client.js`:\n\n```javascript\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js'\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'\n\nconst transport = new StdioClientTransport({\n  command: 'node',\n  args: ['./index.js'],\n})\n\nconst client = new Client({\n  name: 'test-client',\n  version: '1.0.0',\n})\n\nawait client.connect(transport)\n\n// List available tools\nconst tools = await client.listTools()\nconsole.log('Available tools:', tools)\n\n// Test transcript extraction\nconst result = await client.callTool({\n  name: 'get_transcript',\n  arguments: {\n    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',\n  },\n})\n\nconsole.log('Transcript:', result.content[0].text)\nawait transport.close()\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n1. **\"No transcript available\"**\n\n   - ✓ Ensure the video has captions/subtitles available\n   - ✓ Check if the video is public and not age-restricted\n   - ✓ Some live streams may not have transcripts available\n\n2. **Connection errors**\n\n   - ✓ Verify your internet connection\n   - ✓ Check if YouTube is accessible in your region\n   - ✓ Ensure Node.js version is 18.0 or higher\n\n3. **MCP server not found in Claude**\n\n   - ✓ Verify the path in your Claude configuration is absolute\n   - ✓ Ensure Node.js is properly installed and in PATH\n   - ✓ Restart Claude Desktop after configuration changes\n\n4. **Permission errors when saving files**\n   - ✓ Ensure write permissions in the target directory\n   - ✓ Check disk space availability\n\n### Debug Mode\n\nEnable debug logging by setting the environment variable:\n\n```bash\nDEBUG=youtube-transcript-mcp node index.js\n```\n\n## 📊 Performance\n\n- Average transcript extraction time: 1-3 seconds\n- Memory usage: ~50MB\n- Supports videos up to 12+ hours in length\n- Handles 1000+ segments efficiently\n\n## 🤝 Contributing\n\nContributions are welcome! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Follow existing code style\n- Add tests for new features\n- Update documentation as needed\n- Ensure all tests pass before submitting PR\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## 🙏 Acknowledgments\n\n- [youtubei.js](https://github.com/LuanRT/YouTube.js) - Excellent YouTube API implementation\n- [Model Context Protocol](https://github.com/anthropics/mcp) - MCP SDK and specification\n- [Anthropic](https://www.anthropic.com) - For creating Claude and the MCP protocol\n\n## 📈 Roadmap\n\n- [ ] Support for multiple language transcripts\n- [ ] Batch processing for multiple videos\n- [ ] Transcript translation capabilities\n- [ ] Export to SRT/VTT subtitle formats\n- [ ] Caching for improved performance\n- [ ] Support for playlist extraction\n- [ ] Real-time transcript streaming\n- [ ] Custom formatting options\n\n## 💬 Support\n\nFor issues, questions, or suggestions:\n\n- 🐛 [Open an issue](https://github.com/tanush-yadav/youtube-transcript-mcp/issues)\n- 💡 [Start a discussion](https://github.com/tanush-yadav/youtube-transcript-mcp/discussions)\n- 📧 Contact: tanush@cintra.run\n\n## 📝 Changelog\n\n### [1.0.0] - 2024-01-03\n\n- 🎉 Initial release\n- ✨ Transcript extraction with youtubei.js\n- ⏱️ Timestamp support\n- 📊 Metadata extraction\n- 💾 File saving capability\n- 🔧 MCP protocol implementation\n\n---\n\nMade with ❤️ by the Open Source Community\n\n**Star ⭐ this repo if you find it useful!**\n","readmeFilename":"README.md","_rev":"1-5b9abf6da15f426f15100a649be78591"}