youtube-knowledge-base-mcp

# 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