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 package manager
- One of: Voyage API key, OpenAI API key, or local Ollama
Setup
git clone https://github.com/yourusername/youtube-knowledge-base-mcp.git
cd youtube-knowledge-base-mcp
uv sync
Environment
cp .env.example .env
Add your API key (at least one required):
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:
{
"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.
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):
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:
export YOUTUBE_KB_DATA_DIR=/path/to/custom/location
Or in Claude Desktop config:
{
"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):
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