# YouTube Knowledge Base MCP
An MCP server that builds a searchable knowledge base from video content.
## Why
We consume more content than we can remember. Videos watched, podcasts heard, lectures attended—the information fades. This project builds a searchable knowledge base from that content. Start with YouTube, expand to other sources.
The key: it's an MCP server. Plug it into any LLM (Claude, GPT, local models) and your AI assistant can search everything you've ever watched. Your memory, augmented.
## Features
- Extract transcripts from YouTube videos
- Hybrid search (semantic + keyword)
- Timestamped links to exact video moments
- Organize with tags and notes
- Multiple embedding providers (Voyage, OpenAI, local)
## Installation
### Requirements
- Python 3.10+
- [uv](https://github.com/astral-sh/uv) package manager
- One of: Voyage API key, OpenAI API key, or local Ollama
### Setup
```bash
git clone https://github.com/yourusername/youtube-knowledge-base-mcp.git
cd youtube-knowledge-base-mcp
uv sync
```
### Environment
```bash
cp .env.example .env
```
Add your API key (at least one required):
```env
VOYAGE_API_KEY=your_key_here
# or
OPENAI_API_KEY=your_key_here
```
## Usage
### With Claude Desktop (recommended)
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"youtube-kb": {
"command": "uv",
"args": ["--directory", "/path/to/youtube-knowledge-base-mcp", "run", "youtube-kb"]
}
}
}
```
Then ask Claude: *"Add this video to my knowledge base: [URL]"*
### With Python
See `demo.ipynb` for interactive examples.
```python
from youtube_knowledgebase_mcp import process_video, search
# Add a video
result = await process_video("https://youtube.com/watch?v=...")
# Search
results = await search("What is context engineering?")
for r in results.results:
print(r.timestamp_link) # Jump to exact moment
```
## MCP Tools
4 workflow-based tools designed for LLM efficiency:
| Tool | Description |
|------|-------------|
| `process_video` | Add a video to the knowledge base (with optional tags/summary) |
| `manage_source` | Update tags and summary for a source |
| `explore_library` | Browse sources, list tags, or get statistics |
| `search` | Hybrid semantic + keyword search with reranking |
## Developer CLI
Administrative commands for database management (not exposed to LLMs):
```bash
uv run kb db stats # Show database statistics
uv run kb db reset --confirm # Reset database (destructive)
uv run kb db migrate <path> # Move database to new location
uv run kb source list # List all sources
uv run kb source delete <id> # Delete a source
uv run kb health # System health check
uv run kb import-urls <file> # Bulk import from file
```
Run `uv run kb --help` for all commands.
## Configuration
### Data Location
By default, data is stored in your OS's standard application data directory:
- **macOS**: `~/Library/Application Support/youtube-kb/`
- **Linux**: `~/.local/share/youtube-kb/`
- **Windows**: `%APPDATA%/youtube-kb/`
> **Note**: If you have existing data in `./data/` from a previous version, it will continue to be used automatically.
To use a custom location, set the `YOUTUBE_KB_DATA_DIR` environment variable:
```bash
export YOUTUBE_KB_DATA_DIR=/path/to/custom/location
```
Or in Claude Desktop config:
```json
{
"mcpServers": {
"youtube-kb": {
"command": "uv",
"args": ["--directory", "/path/to/repo", "run", "youtube-kb"],
"env": {
"YOUTUBE_KB_DATA_DIR": "/custom/data/path"
}
}
}
}
```
### Moving Your Database
To move your database to a new location (e.g., Dropbox):
```bash
uv run kb db migrate ~/Dropbox/youtube-kb --confirm
```
Then follow the printed instructions to set the environment variable.
## Architecture
```
youtube_knowledgebase_mcp/
├── core/ # Config, models, database, embeddings
├── repositories/ # Data access layer (LanceDB)
├── services/ # Business logic (search, ingestion, organization)
├── mcp_tools.py # MCP tools (4 workflow-based tools)
└── cli.py # Developer CLI for admin operations
```
### Tech Stack
- **LanceDB** - Vector database with hybrid search
- **yt-dlp** - YouTube transcript extraction
- **Embeddings** - Voyage (default), OpenAI, BGE, Ollama
- **FastMCP** - MCP server framework
## License
MIT
