Pentestic YouTube - MCP Server

A Model Context Protocol (MCP) server that enables retrieval of transcripts from YouTube videos. This server provides direct access to video captions and subtitles through a simple interface.

Features

• 🎥 Extract transcripts from YouTube videos
• 🌍 Multi-language support
• 🔗 Support for multiple URL formats (youtube.com, youtu.be, direct video ID)
• 📊 Detailed metadata in responses
• ⚡ Built with TypeScript for type safety
• 🛡️ Robust error handling

Prerequisites

• Node.js 18 or higher
• npm or yarn

Installation

Local Development

1. Navigate to the project:

cd /home/pentestic/CascadeProjects/pentestic-youtube

2. Install dependencies:

npm install

3. Build the server:

npm run build

For Development with Auto-rebuild

npm run watch

Configuration

Claude Desktop

To use with Claude Desktop, add this server configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "pentestic-youtube": {
      "command": "node",
      "args": ["/home/pentestic/CascadeProjects/pentestic-youtube/dist/index.js"]
    }
  }
}

Tools

get_transcript

Extract transcripts from YouTube videos.

Parameters:

• url (string, required): YouTube video URL or video ID
  • Supports: https://www.youtube.com/watch?v=VIDEO_ID
  • Supports: https://youtu.be/VIDEO_ID
  • Supports: Direct video ID (11 characters)
• lang (string, optional, default: "en"): Language code for transcript
  • Examples: 'en', 'ko', 'es', 'fr', 'de', 'ja', etc.

Response:

• Transcript text
• Metadata:
  • videoId: Extracted video ID
  • language: Language code used
  • timestamp: ISO timestamp of extraction
  • charCount: Character count of transcript

Usage Examples

Example 1: Get English transcript by URL

await server.callTool("get_transcript", {
  url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  lang: "en"
});

Example 2: Get Korean transcript by video ID

await server.callTool("get_transcript", {
  url: "dQw4w9WgXcQ",
  lang: "ko"
});

Example 3: Using with Claude Desktop

Extract subtitles from https://youtu.be/dQw4w9WgXcQ

Development

Project Structure

pentestic-youtube/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Testing with MCP Inspector

npm run inspector

The MCP Inspector provides a web interface for testing your MCP server during development.

Error Handling

The server implements comprehensive error handling for:

• ❌ Invalid video URLs or IDs
• ❌ Unavailable transcripts
• ❌ Language availability issues
• ❌ Network errors
• ❌ Invalid parameters

All errors include descriptive messages to help with troubleshooting.

Security Considerations

• ✅ Validates all input parameters
• ✅ Handles YouTube API errors gracefully
• ✅ Provides detailed error messages
• ✅ No API keys required (uses public captions)

Architecture

Components

1. YouTubeTranscriptExtractor

   • Extracts video IDs from various URL formats
   • Retrieves transcripts using youtube-captions-scraper
   • Formats transcript data

2. TranscriptServer

   • Implements MCP server protocol
   • Handles tool registration and execution
   • Manages error handling and lifecycle

Technology Stack

• Runtime: Node.js 18+
• Language: TypeScript 5.6+
• Framework: Model Context Protocol SDK 0.6.0
• Library: youtube-captions-scraper 2.0.3

Troubleshooting

Common Issues

Issue: "Failed to retrieve transcript"

• Solution: Check if the video has captions available
• Solution: Try a different language code

Issue: "Invalid YouTube video ID"

• Solution: Ensure the URL is correct and the video exists
• Solution: Check if the video is public

Issue: Server not responding

• Solution: Check if the server is built (npm run build)
• Solution: Verify Node.js version (18+)

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Based on the original work by kimtaeyoon83/mcp-server-youtube-transcript