Mcptube
No description available
Ask AI about Mcptube
Powered by Claude Β· Grounded in docs
I know everything about Mcptube. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π¬ mcptube
Convert any YouTube video into an AI-queryable MCP server.
mcptube extracts metadata, transcripts, and frames from YouTube videos, indexes them for semantic search, and exposes everything as both a CLI tool and an MCP (Model Context Protocol) server. Ask questions, generate reports, discover new videos, and synthesize themes β all from your terminal or AI assistant.
β¨ Features
| Feature | CLI | MCP Server |
|---|---|---|
| Add/remove YouTube videos | β | β |
| List library with tags | β | β |
| Full video details + transcript | β | β |
| Semantic search (single/cross-video) | β | β |
| Frame extraction by timestamp | β | β |
| Frame extraction by query | β | β |
| Ask questions about videos | β (BYOK) | β (passthrough) |
| LLM classification/tagging | β (BYOK) | β (passthrough) |
| Illustrated reports (single video) | β (BYOK) | β (passthrough) |
| Cross-video reports | β (BYOK) | β (passthrough) |
| YouTube discovery + clustering | β (BYOK) | β |
| Cross-video synthesis | β (BYOK) | β (passthrough) |
| Smart video resolver (ID/index/text) | β | β |
BYOK = Bring Your Own Key (Anthropic, OpenAI, or Google) Passthrough = The MCP client's own LLM does the analysis β zero API key required on the server
π¦ Installation
Prerequisites
- Python 3.12 or 3.13 (ChromaDB is not yet compatible with Python 3.14)
- ffmpeg β required for frame extraction (install guide)
Recommended: pipx (CLI + MCP server)
pipx install mcptube --python python3.12
This installs mcptube globally and makes it available to all MCP clients without activating a virtual environment.
Alternative: pip (virtual environment)
python3.12 -m venv venv
source venv/bin/activate
pip install mcptube
β οΈ macOS/Homebrew users: Global
pip installwill fail with "externally-managed-environment". Usepipxor a virtual environment instead.
Verify installation
mcptube --help
π Quick Start
# 1. Add a YouTube video
mcptube add "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 2. List your library
mcptube list
# 3. Search the transcript
mcptube search "main topic"
# 4. Extract a frame at 30 seconds
mcptube frame 1 30
# 5. Ask a question about it
mcptube ask "What is this video about?" -v 1
π‘ Always wrap multi-word arguments in double quotes β e.g.
mcptube search "neural networks", notmcptube search neural networks.
π CLI Reference
Library Management
| Command | Description | Example |
|---|---|---|
mcptube add "<url>" | Ingest a YouTube video | mcptube add "https://youtu.be/dQw4w9WgXcQ" |
mcptube list | List all videos with tags | mcptube list |
mcptube info <query> | Show full video details | mcptube info 1 or mcptube info "dQw4w9WgXcQ" |
mcptube remove <query> | Remove a video | mcptube remove 1 |
Search & Frames
| Command | Description | Example |
|---|---|---|
mcptube search "<query>" | Semantic search across all videos | mcptube search "machine learning" |
mcptube search "<query>" --video <id> | Search within a specific video | mcptube search "intro" --video 1 |
mcptube frame <video> <timestamp> | Extract frame at timestamp | mcptube frame 1 30 |
mcptube frame-query <video> "<query>" | Extract frame by transcript match | mcptube frame-query 1 "key moment" |
Ask Questions (BYOK)
| Command | Description | Example |
|---|---|---|
mcptube ask "<question>" -v <video> | Ask about a single video | mcptube ask "What are the main points?" -v 1 |
mcptube ask "<question>" -v <id1> -v <id2> | Ask across multiple videos | mcptube ask "What do they agree on?" -v 1 -v 2 |
Analysis & Reports (BYOK)
| Command | Description | Example |
|---|---|---|
mcptube classify <video> | LLM classification/tagging | mcptube classify 1 |
mcptube report <video> [--focus] [--format] [-o] | Single-video illustrated report | mcptube report 1 --format html -o report.html |
mcptube report-query "<topic>" [--tag] [--format] [-o] | Cross-video report | mcptube report-query "AI trends" --format html -o report.html |
mcptube discover "<topic>" | YouTube search + LLM clustering | mcptube discover "prompt engineering" |
mcptube synthesize-cmd "<topic>" -v <id1> -v <id2> | Cross-video synthesis | mcptube synthesize-cmd "AI" -v abc123 -v xyz789 --format html -o synthesis.html |
Server
| Command | Description | Example |
|---|---|---|
mcptube serve | Start MCP server (Streamable HTTP) | mcptube serve |
mcptube serve --stdio | Start MCP server (stdio transport) | mcptube serve --stdio |
mcptube serve --host 0.0.0.0 --port 8080 | Custom host/port | mcptube serve --host 0.0.0.0 --port 8080 |
Smart Video Resolver
All commands that accept a <video> or <query> argument support the smart resolver:
| Input | Resolution |
|---|---|
dQw4w9WgXcQ | Exact YouTube video ID |
1 | Index number from mcptube list (1-based) |
"prompting" | Case-insensitive substring match on title or channel |
π MCP Server
mcptube exposes 17 MCP tools that any MCP-compatible AI assistant can use.
Transport Modes
| Mode | Command | Use Case |
|---|---|---|
| Streamable HTTP | mcptube serve | Claude Code, remote clients |
| stdio | mcptube serve --stdio | VS Code Copilot, Claude Desktop, Cursor |
MCP Tools
| Tool | Description | API Key Required |
|---|---|---|
add_video(url) | Ingest a YouTube video | No |
remove_video(video_id) | Remove from library | No |
list_videos() | List all videos | No |
get_info(video_id) | Full details + transcript | No |
search(query, video_id?, limit) | Semantic search (single video) | No |
search_library(query, tags?, limit) | Semantic search (all videos) | No |
get_frame(video_id, timestamp) | Extract frame (returns image) | No |
get_frame_by_query(video_id, query) | Search + extract frame | No |
get_frame_data(video_id, timestamp) | Frame as base64 | No |
ask_video(video_id, question) | Ask about a video (passthrough) | No |
ask_videos(video_ids, question) | Ask across videos (passthrough) | No |
classify_video(video_id) | Get metadata for classification | No |
save_tags(video_id, tags) | Save classification tags | No |
generate_report(video_id, query?) | Report data (passthrough) | No |
generate_report_from_query(query, tags?) | Cross-video report data | No |
discover_videos(topic) | YouTube search results | No |
synthesize(video_ids, topic) | Cross-video synthesis data | No |
Passthrough tools return raw data (transcripts, metadata) for the connected AI to analyze. This means zero API key cost on the server β the client's own LLM does the work.
π₯οΈ MCP Client Setup
Claude Code (Streamable HTTP)
- Start the mcptube server:
mcptube serve
- In a separate terminal, add the MCP server to Claude Code:
claude mcp add --transport http mcptube http://127.0.0.1:9093/mcp
- Start using it:
> Use mcptube to add this video: https://www.youtube.com/watch?v=dQw4w9WgXcQ
> Search mcptube for "main topic"
> Generate a report for the first video
π‘ Claude Code has terminal access, so it can also run CLI commands directly for better report quality.
VS Code Copilot (stdio)
- Open MCP configuration (Cmd+Shift+P β "MCP: Open User Configuration") or create
.vscode/mcp.jsonin your workspace:
{
"servers": {
"mcptube": {
"command": "mcptube",
"args": ["serve", "--stdio"]
}
}
}
-
Click the Start button next to the server entry.
-
Open Copilot Chat in Agent Mode and start using mcptube tools.
β οΈ If you installed mcptube in a virtual environment (not via
pipx), you'll need the full path to the executable. Find it withwhich mcptube.
Claude Desktop (stdio)
- Open the config file:
open ~/Library/Application\ Support/Claude/claude_desktop_config.json
- Add the mcptube server:
{
"mcpServers": {
"mcptube": {
"command": "/Users/<your-username>/.local/bin/mcptube",
"args": ["serve", "--stdio"]
}
}
}
π‘ Use the full path to
mcptube(find it withwhich mcptube). If you usedpipx, it's typically at~/.local/bin/mcptube.
- Restart Claude Desktop. You should see a tools icon (π¨) in the chat input.
Cursor (stdio)
- Open Cursor Settings β MCP Servers, or edit
.cursor/mcp.json:
{
"mcpServers": {
"mcptube": {
"command": "mcptube",
"args": ["serve", "--stdio"]
}
}
}
- Restart Cursor and use mcptube tools in Agent mode.
π API Keys (BYOK)
Some CLI features require an LLM API key. Set one of:
export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...
# or
export GOOGLE_API_KEY=AI...
What requires a key?
| Feature | CLI | MCP |
|---|---|---|
| Add video | No (auto-classifies if key set) | No |
| Search / Frames | No | No |
| Ask questions | β Key required | No (passthrough) |
| Classify | β Key required | No (passthrough) |
| Reports | β Key required | No (passthrough) |
| Discover | β Key required | No (via yt-dlp) |
| Synthesize | β Key required | No (passthrough) |
MCP passthrough = The connected AI assistant (Claude, Copilot, etc.) analyzes the data using its own model. No API key needed on the mcptube server.
βοΈ CLI (BYOK) vs MCP: When to Use Which
| CLI with BYOK | MCP Passthrough | |
|---|---|---|
| Speed | Faster β direct API call | Slower β client processes raw data |
| Accuracy | More deterministic β fine-tuned prompts per task | Depends on client LLM interpretation |
| Frame selection | Guided by specialized prompts | Client may hallucinate timestamps |
| Context limits | No limit (streams to LLM API) | May exceed client context window on long videos |
| Cost | Uses your API key | Zero cost β uses client's own model |
| Output | Markdown or HTML files | Inline in chat |
Recommendation: Use CLI commands for reports, synthesis, and discovery. Use MCP tools for quick queries, search, and frame extraction.
π Workflows
Discovery β Add β Synthesize
# 1. Scout YouTube for relevant videos
mcptube discover "transformer architecture"
# 2. Add interesting videos to your library
mcptube add "https://www.youtube.com/watch?v=..."
mcptube add "https://www.youtube.com/watch?v=..."
# 3. Synthesize themes across them
mcptube synthesize-cmd "attention mechanisms" -v <id1> -v <id2> --format html -o synthesis.html
π
discoverresults are NOT in your library. You mustaddthem before you can search, ask, or synthesize.
Ask β Deep Dive β Report
# 1. Ask a quick question
mcptube ask "What are the main arguments?" -v 1
# 2. Search for specific moments
mcptube search "key conclusion" --video 1
# 3. Extract a frame at that moment
mcptube frame 1 245
# 4. Generate a full illustrated report
mcptube report 1 --format html -o report.html
βοΈ Environment Variables
| Variable | Default | Description |
|---|---|---|
MCPTUBE_DATA_DIR | ~/.mcptube | Root directory for all data (DB, frames, ChromaDB) |
MCPTUBE_FRAMES_DIR | <data_dir>/frames | Directory for cached extracted frames |
MCPTUBE_HOST | 127.0.0.1 | Server bind host |
MCPTUBE_PORT | 9093 | Server bind port |
ANTHROPIC_API_KEY | β | Anthropic API key (for CLI BYOK features) |
OPENAI_API_KEY | β | OpenAI API key (for CLI BYOK features) |
GOOGLE_API_KEY | β | Google API key (for CLI BYOK features) |
ποΈ Architecture
CLI (Typer) ββββββββ
βββ Service Layer (McpTubeService)
MCP Server (FastMCP) βββ β
ββββββ΄βββββ
Repository VectorStore
(SQLite) (ChromaDB)
β
Ingestion Layer
βββ YouTubeExtractor (yt-dlp)
βββ FrameExtractor (yt-dlp + ffmpeg)
βββ LLMClient (LiteLLM β CLI only)
βββ ReportBuilder (CLI only)
βββ VideoDiscovery (CLI only)
β οΈ Known Issues & Limitations
- Frame storage: Frames are cached in
~/.mcptube/frames(hidden directory). Override withMCPTUBE_FRAMES_DIR. - Python 3.14: ChromaDB is not yet compatible with Python 3.14. Use Python 3.12 or 3.13.
- Long transcripts: Very long videos may exceed MCP client context limits in passthrough mode. CLI BYOK is recommended for long-form content.
- Multi-video frame accuracy: Cross-video reports may occasionally select frames from the wrong video. CLI reports use stricter prompts for better accuracy.
- Claude Desktop: Report generation may fail on context-heavy operations. Use shorter videos or CLI for reports.
get_frame_data: Returns base64-encoded frames that can exceed client token limits (50K+ characters). Preferget_framefor inline display.- Concurrent access: Running CLI and MCP server simultaneously may cause SQLite conflicts.
π§ͺ Development
git clone https://github.com/0xchamin/mcptube.git
cd mcptube
pip install -e ".[dev]"
pytest -v
π License
MIT License β see LICENSE for details.
