https://github.com/fabioc-aloha/youtube-mcp-server
🎬 Comprehensive YouTube MCP Server with 31 tools, AI intelligence layer, learning path generator, content repurposing, and watch history analysis
https://github.com/fabioc-aloha/youtube-mcp-server
ai ai-agents ai-tools content-creation flashcards github-copilot knowledge-extraction learning llm-tools mcp model-context-protocol quiz-generator typescript video-analysis youtube youtube-api
Last synced: 19 days ago
JSON representation
🎬 Comprehensive YouTube MCP Server with 31 tools, AI intelligence layer, learning path generator, content repurposing, and watch history analysis
- Host: GitHub
- URL: https://github.com/fabioc-aloha/youtube-mcp-server
- Owner: fabioc-aloha
- Created: 2026-01-26T04:21:59.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-26T15:07:28.000Z (5 months ago)
- Last Synced: 2026-01-26T19:33:19.226Z (5 months ago)
- Topics: ai, ai-agents, ai-tools, content-creation, flashcards, github-copilot, knowledge-extraction, learning, llm-tools, mcp, model-context-protocol, quiz-generator, typescript, video-analysis, youtube, youtube-api
- Language: TypeScript
- Size: 310 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
**Think • Build • Deploy** — *Transform YouTube into a knowledge engine for AI agents*
---
An intelligent Model Context Protocol (MCP) server that turns AI assistants into YouTube research powerhouses. Go beyond simple video searches—synthesize knowledge across multiple videos, extract structured concepts, and conduct deep research with AI-native tools.
[](https://modelcontextprotocol.io)
[](https://www.npmjs.com/package/youtube-mcp-tools)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](LICENSE)
---
## ✨ What Makes This Different
### vs Other YouTube MCP Servers
| Feature | anaisbetts | kimtaeyoon83 | ZubeidHendricks | yutu (Go) | **YouTube MCP Tools** |
| ---------------------------------- | ---------- | ------------ | --------------- | --------- | --------------------------- |
| Transcripts | ✅ | ✅ | ✅ | ✅ | ✅ Multi-strategy fallback |
| Video metadata | ❌ | ❌ | ✅ | ✅ | ✅ Full |
| Channel analytics | ❌ | ❌ | ✅ | ✅ | ✅ Full |
| Playlist support | ❌ | ❌ | ✅ | ✅ | ✅ Full |
| **Semantic chunking** | ❌ | ❌ | ❌ | ❌ | ✅**Unique** |
| **Concept extraction** | ❌ | ❌ | ❌ | ❌ | ✅**Unique** |
| **Multi-video synthesis** | ❌ | ❌ | ❌ | ❌ | ✅**Unique** |
| **Research workflows** | ❌ | ❌ | ❌ | ❌ | ✅**Unique** |
| **Learning path generation** | ❌ | ❌ | ❌ | ❌ | ✅**Unique** |
| **Flashcard generation** | ❌ | ❌ | ❌ | ❌ | ✅**Unique** |
| **Content repurposing** | ❌ | ❌ | ❌ | ❌ | ✅**Unique** |
| Smart caching | ❌ | ❌ | ⚠️ Basic | ❌ | ✅ Full LRU + TTL |
| Rate limiting | ❌ | ❌ | ❌ | ❌ | ✅ Quota-aware |
> **The first YouTube MCP with an intelligence layer** — we don't just fetch data, we understand it.
### vs Raw YouTube API
| Traditional YouTube API | YouTube MCP Tools |
| ------------------------- | -------------------------------------------- |
| Returns raw video data | Returns**structured knowledge** |
| Single video queries | **Multi-video synthesis** |
| Text search only | **Semantic concept extraction** |
| Manual transcript parsing | **AI-ready chunked content** |
| No cross-video analysis | **Research synthesis with citations** |
| No rate limiting | **Smart quota management** |
| Raw errors | **Graceful error handling & recovery** |
---
## 🚀 Quick Start
### Installation
```bash
# Install globally
npm install -g youtube-mcp-tools
# Or use directly with npx (no install needed)
npx youtube-mcp-tools
```
### VS Code / GitHub Copilot Setup
Add to your VS Code `settings.json`:
```json
{
"mcp": {
"servers": {
"youtube": {
"command": "npx",
"args": ["-y", "youtube-mcp-tools"],
"env": {
"YOUTUBE_API_KEY": "your_api_key"
}
}
}
}
}
```
### Claude Desktop Setup
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"youtube": {
"command": "npx",
"args": ["-y", "youtube-mcp-tools"],
"env": {
"YOUTUBE_API_KEY": "your_api_key"
}
}
}
}
```
---
## 🧠 Intelligence Layer
The magic happens in the intelligence layer—purpose-built for AI agents:
### 🔬 Research Synthesis
> "Compare how these 5 videos explain React Server Components"
> → Returns consensus points, controversies, unique insights, and citations
### 📚 Concept Extraction
> "What concepts does this tutorial cover?"
> → Returns structured topics with difficulty levels, prerequisites, and relationships
### ✂️ Smart Chunking
> "Prepare this 2-hour lecture for analysis"
> → Returns AI-optimized chunks respecting sentence boundaries and context
---
## 🛠️ Tools Overview
**40 powerful tools + 3 MCP resources** organized by capability:
| Category | Count | Highlights |
| -------------------------------- | ----- | ---------------------------------------------------------------- |
| 🔍**Search & Discovery** | 4 | Search, date filtering, related videos, trending |
| 📺**Channel Intelligence** | 5 | Stats, analytics, popular videos, playlists |
| 🎬**Video Analysis** | 6 | Details, comparison, comments, batch operations |
| 📝**Transcripts** | 4 | Full captions, search, chunking, retrieval |
| 🧠**AI Intelligence** | 5 | Deep analysis, concept extraction, research synthesis |
| 📚**Learning Tools** | 5 | Flashcards, quizzes, learning paths, study guides, watch history |
| 🎨**Creator Tools** | 2 | Content repurposing, gap analysis |
| 👤**User Preferences** | 1 | Personalized recommendations, trusted/excluded channels |
| 🔮**Semantic Search** | 5 | Vector embeddings, similarity search, clustering |
| 🔴**Live & Trending** | 3 | Live streams, trending by region, categories |
| 📦**MCP Resources** | 3 | Cache stats, quota status, preferences (zero cost) |
[📖 **Full Tool Reference** →](TOOLS.md) | [📚 **Examples** →](EXAMPLES.md) | [🎬 **Demo Guide** →](DEMO.md)
---
## 🛡️ Production Ready
Built for reliability in production environments:
| Feature | Description |
| --------------------------- | --------------------------------------------------------------- |
| **Rate Limiting** | Smart quota management tracks API usage and prevents exhaustion |
| **Graceful Shutdown** | Clean termination with SIGINT/SIGTERM signal handling |
| **Input Validation** | Zod-based schema validation for all tool inputs |
| **Config Validation** | Fail-fast startup with clear error messages for missing config |
| **Secure Logging** | Automatic redaction of API keys and sensitive data |
| **Error Recovery** | Wrapped API calls with typed error handling |
| **LRU Caching** | Intelligent caching for transcripts and analysis results |
| **ESLint** | TypeScript-aware linting for code quality |
---
## 🎯 Use Cases
### 📚 Research & Learning
- Synthesize knowledge from multiple educational videos
- Generate flashcards and quizzes from any tutorial
- Extract structured learning paths with prerequisites
- Compare teaching approaches across instructors
### 📊 Content Analysis
- Analyze competitor content strategies
- Track trending topics in your niche
- Identify content gaps and opportunities
- Benchmark channel performance
### 🎨 Content Creation
- Repurpose videos into blog posts, tweets, newsletters
- Generate podcast show notes from interviews
- Create short-form scripts from long content
- Plan content strategy with gap analysis
### 🤖 AI Agent Workflows
- Build YouTube-powered research assistants
- Create automated content summarization pipelines
- Develop knowledge base builders from video content
---
## 🏗️ Architecture
```text
┌───────────────────────────────────────────────┐
│ MCP Protocol │
├───────────────────────────────────────────────┤
│ Tools (40) │ Prompts (5) │ Resources (3) │
├──────────────┴───────────────┴────────────────┤
│ Intelligence Layer │
│ ┌─────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Chunker │ │ Analyzer │ │ Synthesis │ │
│ ├─────────┤ ├──────────┤ ├───────────┤ │
│ │ Quiz │ │ Learning │ │ Repurpose │ │
│ │Generator│ │ Path │ │ Content │ │
│ ├─────────┤ ├──────────┤ ├───────────┤ │
│ │ Watch │ │ Content │ │Flashcards │ │
│ │ History │ │ Gaps │ │ │ │
│ └─────────┘ └──────────┘ └───────────┘ │
├───────────────────────────────────────────────┤
│ Semantic Search Layer │
│ ┌─────────┐ ┌──────────┐ ┌───────────┐ │
│ │Embedding│ │ Vector │ │ Clustering│ │
│ │ Service │ │ Store │ │ (k-means)│ │
│ └─────────┘ └──────────┘ └───────────┘ │
├───────────────────────────────────────────────┤
│ Production Infrastructure │
│ ┌─────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Rate │ │ Graceful │ │ Input │ │
│ │ Limiter │ │ Shutdown │ │ Validator │ │
│ └─────────┘ └──────────┘ └───────────┘ │
├───────────────────────────────────────────────┤
│ Cache Layer (LRU + Vectors) │
├───────────────────────────────────────────────┤
│ YouTube Data API v3 + Transcripts │
└───────────────────────────────────────────────┘
```
---
## 📈 Roadmap
- [X] **Phase 1**: Core YouTube API integration (18 tools)
- [X] **Phase 2**: Intelligence layer (analysis, synthesis)
- [X] **Phase 3**: Learning tools (flashcards, quizzes, learning paths)
- [X] **Phase 4**: Creator tools (content gaps, repurposing)
- [X] **Phase 5**: Personal insights (watch history analysis)
- [X] **Phase 6**: Semantic search & embeddings
- [ ] **Phase 7**: Knowledge graph & entity extraction
- [ ] **Phase 8**: Real-time streaming analysis
[📋 Full Project Plan →](PROJECT-PLAN.md) | [🔮 Vision →](VISION.md)
---
## 🔧 Development
```bash
# Development mode with hot reload
npm run dev
# Run tests
npm test
# Build for production
npm run build
```
---
## 📊 API Quota Guide
YouTube Data API quota: **10,000 units/day**
| Operation | Cost | Notes |
| --------------------- | ----------------- | ---------------------------------- |
| Search | 100 units | Use date ranges to narrow results |
| Video details | 1 unit | Batch up to 50 with `video_list` |
| Channel info | 1 unit | |
| Comments | 1 unit | |
| **Transcripts** | **0 units** | Free! Use liberally |
**💡 Pro Tip**: Transcripts are quota-free. Use `youtube_transcript` and `youtube_transcript_search` for deep content analysis without burning quota.
---
## 🤝 Contributing
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
---
## 📄 License
MIT © 2026 Fabio Caversan
---
Built with 🧠 by Alex • Transforming how AI agents understand video content
© 2026 Fabio Caversan • Think. Build. Deploy.