YTMcp - YouTube Transcript MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to fetch YouTube video transcripts with precise timestamps. Built on top of the excellent youtube-transcript-api by @jdepoix.

🎯 Features

• 🎥 Fetch YouTube transcripts with start/end timestamps
• 🌍 Multi-language support with automatic fallback
• ⏱️ Time-range filtering for specific video segments
• 📋 List available languages for any video
• 🔍 Smart URL parsing - works with any YouTube URL format
• 🤖 MCP compatible - works with Claude Desktop and other MCP clients
• 🚀 Zero external dependencies - bundled with transcript API
• 🛡️ Comprehensive error handling for robust operation

📦 Installation

pip install ytmcp

🚀 Quick Start

1. Run as MCP Server

ytmcp

The server will start and listen for MCP requests via stdio.

2. Configure with Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "ytmcp"
    }
  }
}

3. Test Installation

# Test the server functionality
ytmcp --test

# Test with a specific video
ytmcp --test --video-id dQw4w9WgXcQ

# Check version
ytmcp --version

4. Use with Claude

Once configured, you can ask Claude natural language questions like:

• "Get the transcript for this YouTube video: https://www.youtube.com/watch?v=dQw4w9WgXcQ"
• "What transcript languages are available for this video?"
• "Get me the transcript from 2:30 to 5:00 in this video"
• "Summarize the key points from this YouTube video's transcript"

🛠️ Available Tools

get_transcript

Fetch complete video transcript with timestamps.

Parameters:

• video_url_or_id (required): YouTube URL or video ID
• languages (optional): Array of language codes in priority order (default: ["en"])
• preserve_formatting (optional): Keep HTML formatting (default: false)
• include_timestamps (optional): Include start/end times (default: true)

Example Usage:

{
  "name": "get_transcript",
  "arguments": {
    "video_url_or_id": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "languages": ["en", "es"],
    "include_timestamps": true
  }
}

Example Response:

{
  "video_id": "dQw4w9WgXcQ",
  "language": "English",
  "language_code": "en",
  "is_generated": true,
  "transcript_count": 142,
  "transcript": [
    {
      "text": "We're no strangers to love",
      "start": 15.5,
      "duration": 2.3,
      "end": 17.8
    },
    {
      "text": "You know the rules and so do I",
      "start": 17.8,
      "duration": 2.1,
      "end": 19.9
    }
  ]
}

list_available_transcripts

List all available transcript languages for a video.

Parameters:

• video_url_or_id (required): YouTube URL or video ID

Example Usage:

{
  "name": "list_available_transcripts",
  "arguments": {
    "video_url_or_id": "dQw4w9WgXcQ"
  }
}

Example Response:

{
  "video_id": "dQw4w9WgXcQ",
  "manually_created_transcripts": [
    {
      "language": "English",
      "language_code": "en",
      "is_translatable": true
    }
  ],
  "auto_generated_transcripts": [
    {
      "language": "English (auto-generated)",
      "language_code": "en",
      "is_translatable": true
    }
  ],
  "total_transcripts": 2
}

get_transcript_with_time_range

Get transcript for specific time range.

Parameters:

• video_url_or_id (required): YouTube URL or video ID
• start_time (required): Start time in seconds
• end_time (required): End time in seconds
• languages (optional): Language preferences (default: ["en"])
• preserve_formatting (optional): Keep HTML formatting (default: false)

Example Usage:

{
  "name": "get_transcript_with_time_range",
  "arguments": {
    "video_url_or_id": "dQw4w9WgXcQ",
    "start_time": 30.0,
    "end_time": 90.0,
    "languages": ["en"]
  }
}

Example Response:

{
  "video_id": "dQw4w9WgXcQ",
  "language": "English",
  "language_code": "en",
  "is_generated": true,
  "time_range": {
    "start": 30.0,
    "end": 90.0
  },
  "filtered_transcript": [
    {
      "text": "Never gonna give you up",
      "start": 32.1,
      "duration": 1.8,
      "end": 33.9
    }
  ],
  "snippet_count": 15
}

🔧 Configuration Options

Language Codes

YTMcp supports all language codes that YouTube provides. Common ones include:

• en - English
• es - Spanish
• fr - French
• de - German
• it - Italian
• pt - Portuguese
• ru - Russian
• ja - Japanese
• ko - Korean
• zh - Chinese

URL Format Support

YTMcp automatically extracts video IDs from various YouTube URL formats:

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://www.youtube.com/embed/VIDEO_ID
• https://www.youtube.com/watch?v=VIDEO_ID&t=120s
• Or just the video ID directly: VIDEO_ID

⚠️ Error Handling

YTMcp provides comprehensive error handling for various scenarios:

Common Error Types

• Invalid Video ID: Invalid URL or video ID format
• No Transcript Found: No transcripts available in requested languages
• Transcripts Disabled: Video has disabled subtitles/captions
• Video Unavailable: Video is private, deleted, or restricted
• Request Blocked: IP blocked by YouTube (consider using proxies)
• Age Restricted: Video requires authentication

Error Response Format

{
  "content": [
    {
      "type": "text",
      "text": "Error: No transcript found for languages: ['de']"
    }
  ]
}

🔄 Advanced Usage

Running as Python Module

python -m ytmcp

Development Mode

# Install in development mode
pip install -e .

# Run tests
ytmcp --test

# Test with verbose output
ytmcp --test --video-id dQw4w9WgXcQ

Proxy Support

If you encounter IP blocking issues, you can extend the server by modifying the YouTube API configuration to use proxies. See the youtube-transcript-api documentation for proxy configuration options.

📚 Use Cases

Content Analysis

• Video Summarization: Extract transcripts for AI-powered summaries
• Content Research: Analyze video content programmatically
• Educational Tools: Create study materials from lecture videos

Accessibility

• Transcript Generation: Provide text alternatives for video content
• Translation: Use with translation APIs for multilingual access
• Search & Discovery: Make video content searchable

Development

• API Integration: Embed transcript functionality in applications
• Data Pipeline: Process video transcripts in bulk
• AI Training: Use transcripts as training data

🐛 Troubleshooting

Installation Issues

# If you get import errors
pip install --upgrade ytmcp

# If command not found
pip install --force-reinstall ytmcp

# Check installation
ytmcp --version

Common Problems

1. Video Not Found

• Verify the video ID/URL is correct
• Check if the video is public and available
• Ensure the video has captions enabled

2. Language Not Available

• Use list_available_transcripts to see available languages
• Try fallback languages like ["en", "auto"]
• Some videos only have auto-generated transcripts

3. Rate Limiting

• YouTube may temporarily block requests from your IP
• Consider using proxy configuration for high-volume usage
• Space out your requests to avoid hitting rate limits

4. Permission Errors

• Check file permissions if running on Unix systems
• Ensure Python has permission to execute the script
• Try running with appropriate user privileges

🤝 Contributing

We welcome contributions! Here's how you can help:

Development Setup

git clone https://github.com/shubhamshnd/ytmcp.git
cd ytmcp
pip install -e ".[dev]"

Running Tests

pytest tests/

Code Style

black ytmcp/
flake8 ytmcp/
mypy ytmcp/

Submitting Changes

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

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

🙏 Credits

This project is built on top of the excellent youtube-transcript-api by @jdepoix. All core transcript fetching functionality is provided by this library.

Key Dependencies:

• youtube-transcript-api - Core YouTube transcript fetching (bundled)
• requests - HTTP library for API calls
• defusedxml - Secure XML parsing

🔗 Related Projects

• Model Context Protocol - The protocol specification
• Claude Desktop - AI assistant that supports MCP
• youtube-transcript-api - Original transcript API

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: README

🚀 Roadmap

• [ ] Translation Support: Automatic transcript translation
• [ ] Batch Processing: Handle multiple videos simultaneously
• [ ] Caching: Cache transcripts for improved performance
• [ ] WebSocket Support: Real-time transcript streaming
• [ ] Export Formats: SRT, VTT, and other subtitle formats
• [ ] Search: Full-text search within transcripts
• [ ] Webhooks: Notification system for transcript updates

---

Made with ❤️ for the MCP and AI community

If you find this project useful, please consider giving it a ⭐ on GitHub!