A comprehensive YouTube MCP (Model Context Protocol) server that provides AI-powered video analysis, playback control, transcript management, and advanced content processing capabilities.
- Play videos in browser or VLC player
- Audio-only playback with ffplay
- Video segment playback with timestamp control
- Active playback session management
- Get detailed video information (title, views, likes, duration, etc.)
- Fetch playlist details with all videos
- Retrieve channel information and statistics
- Search YouTube videos and music
- Download video thumbnails in multiple qualities
- Get official video transcripts
- AI-powered transcript generation (when official unavailable)
- Translate transcripts to any language
- Format transcripts with or without timestamps
- Generate video summaries with key points
- Auto-generate chapter markers
- Extract relevant keywords with relevance scores
- Detect topics and categories
- Create AI-powered video highlights
- Node.js >= 18.0.0
- npm >= 9.0.0
- Google Gemini API key (required for AI features)
- Optional: VLC Media Player (for VLC playback)
- Optional: FFmpeg (for audio playback and processing)
- Clone the repository:
git clone <repository-url>
cd yt-ninja- Install dependencies:
npm install- Configure environment variables:
cp .env.example .envEdit .env and add your configuration:
# Required
GEMINI_API_KEY=your-google-gemini-api-key
# Optional
DOWNLOAD_DIR=./downloads
TEMP_DIR=./temp
MAX_CONCURRENT_DOWNLOADS=3
LOG_LEVEL=info- Build the project:
npm run build| Variable | Required | Default | Description |
|---|---|---|---|
GEMINI_API_KEY |
Yes | - | Google Generative AI API key for AI features |
DOWNLOAD_DIR |
No | ./downloads |
Directory for downloaded files |
TEMP_DIR |
No | ./temp |
Temporary files directory |
MAX_CONCURRENT_DOWNLOADS |
No | 3 |
Maximum concurrent downloads |
LOG_LEVEL |
No | info |
Logging level (error, warn, info, debug) |
- Visit Google AI Studio
- Sign in with your Google account
- Click "Create API Key"
- Copy the key and add it to your
.envfile
Add to your MCP settings file (mcp.json):
{
"mcpServers": {
"yt-ninja": {
"command": "node",
"args": ["/path/to/yt-ninja/dist/index.js"],
"env": {
"GEMINI_API_KEY": "your-api-key-here"
},
"disabled": false
}
}
}Play a YouTube video in browser or VLC player.
Parameters:
url(string, required): YouTube video URLplayer(string, optional): Player type -browserorvlc(default:browser)
Example:
{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"player": "browser"
}Get comprehensive information about a YouTube video.
Parameters:
url(string, required): YouTube video URL
Returns: Video title, description, channel, views, likes, duration, tags, thumbnail, etc.
Get information about a YouTube playlist.
Parameters:
url(string, required): YouTube playlist URL
Returns: Playlist title, description, video count, total duration, list of videos
Get information about a YouTube channel.
Parameters:
channelId(string, required): Channel ID or URL
Returns: Channel name, description, subscriber count, total views, video count
Search for videos on YouTube.
Parameters:
query(string, required): Search querymaxResults(number, optional): Maximum results (1-50, default: 10)
Returns: Array of search results with video details
Search specifically for music on YouTube.
Parameters:
query(string, required): Music search querymaxResults(number, optional): Maximum results (1-50, default: 10)
Returns: Array of music search results
Download a video thumbnail image.
Parameters:
url(string, required): YouTube video URLoutputPath(string, optional): Output file pathquality(string, optional): Quality -maxres,high,medium,default(default:maxres)
Get the transcript/subtitles of a video.
Parameters:
url(string, required): YouTube video URLlanguage(string, optional): Language code (e.g., 'en', 'es', 'fr')
Returns: Transcript text, language, timestamps, source type
Translate a video transcript to another language.
Parameters:
url(string, required): YouTube video URLtargetLanguage(string, required): Target language code
Returns: Translated transcript with original timestamps
Generate an AI-powered summary of a video.
Parameters:
url(string, required): YouTube video URLmaxWords(number, optional): Maximum words in summary (default: 200)
Returns: Summary text, key points, word count
Auto-generate chapter markers for a video.
Parameters:
url(string, required): YouTube video URL
Returns: Array of chapters with timestamps, titles, and descriptions
Extract relevant keywords from a video.
Parameters:
url(string, required): YouTube video URLcount(number, optional): Number of keywords (default: 15)
Returns: Array of keywords with relevance scores and frequency
Detect topics and categories in a video.
Parameters:
url(string, required): YouTube video URL
Returns: Array of topics with confidence scores and categories
Generate AI-powered video highlights.
Parameters:
url(string, required): YouTube video URLcount(number, optional): Number of highlights (5-10, default: 7)
Returns: Array of highlight moments with timestamps, descriptions, reasons, and scores
AI
Once configured as an MCP server, you can use YT-NINJA through natural language:
"Get information about this video: https://www.youtube.com/watch?v=dQw4w9WgXcQ"
"Summarize this YouTube video in 150 words"
"Generate chapters for this tutorial video"
"Extract the top 20 keywords from this video"
"Get the transcript and translate it to Spanish"
import { dataManager, aiAnalyzer, transcriptManager } from 'yt-ninja';
// Get video info
const videoInfo = await dataManager.getVideoInfo('https://youtube.com/watch?v=...');
// Generate summary
const summary = await aiAnalyzer.summarizeVideo('https://youtube.com/watch?v=...', 200);
// Get transcript
const transcript = await transcriptManager.getTranscript('https://youtube.com/watch?v=...');npm run dev- Run in development mode with hot reloadnpm run build- Build for productionnpm start- Start the production servernpm run lint- Lint codenpm run format- Format code with Prettiernpm run type-check- Check TypeScript types
yt-ninja/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # MCP server setup
│ ├── integrations/ # External service integrations
│ │ ├── youtube.ts # YouTube API client
│ │ ├── genai.ts # Google GenAI client
│ │ ├── ffmpeg.ts # FFmpeg integration
│ │ └── process.ts # Process management
│ ├── managers/ # Feature managers
│ │ ├── DataManager.ts # Data retrieval
│ │ ├── PlaybackManager.ts # Playback control
│ │ ├── TranscriptManager.ts # Transcript operations
│ │ ├── AIAnalyzer.ts # AI analysis
│ │ ├── MediaProcessor.ts # Media processing
│ │ └── AdvancedFeaturesManager.ts # Advanced features
│ ├── types/ # TypeScript type definitions
│ └── utils/ # Utility functions
├── dist/ # Compiled output
├── downloads/ # Downloaded files
├── .env # Environment configuration
└── package.json
YT-NINJA provides detailed error messages with suggestions:
{
"success": false,
"error": {
"code": "INVALID_URL",
"message": "Invalid YouTube video URL",
"details": { "url": "..." },
"suggestions": [
"Provide a valid YouTube video URL",
"Example: https://www.youtube.com/watch?v=VIDEO_ID"
]
}
}