🎬 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

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 install will fail with "externally-managed-environment". Use pipx or 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", not mcptube search neural networks.

📖 CLI Reference

Library Management

Search & Frames

Ask Questions (BYOK)

Analysis & Reports (BYOK)

Server

Smart Video Resolver

All commands that accept a <video> or <query> argument support the smart resolver:

🔌 MCP Server

mcptube exposes 17 MCP tools that any MCP-compatible AI assistant can use.

Transport Modes

MCP Tools

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)

1. Start the mcptube server:

mcptube serve

1. In a separate terminal, add the MCP server to Claude Code:

claude mcp add --transport http mcptube http://127.0.0.1:9093/mcp

1. 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)

1. Open MCP configuration (Cmd+Shift+P → "MCP: Open User Configuration") or create .vscode/mcp.json in your workspace:

{
  "servers": {
    "mcptube": {
      "command": "mcptube",
      "args": ["serve", "--stdio"]
    }
  }
}

1. Click the Start button next to the server entry.

2. 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 with which mcptube.

Claude Desktop (stdio)

1. Open the config file:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

1. Add the mcptube server:

{
  "mcpServers": {
    "mcptube": {
      "command": "/Users/<your-username>/.local/bin/mcptube",
      "args": ["serve", "--stdio"]
    }
  }
}

💡 Use the full path to mcptube (find it with which mcptube). If you used pipx, it's typically at ~/.local/bin/mcptube.

1. Restart Claude Desktop. You should see a tools icon (🔨) in the chat input.

Cursor (stdio)

1. Open Cursor Settings → MCP Servers, or edit .cursor/mcp.json:

{
  "mcpServers": {
    "mcptube": {
      "command": "mcptube",
      "args": ["serve", "--stdio"]
    }
  }
}

1. 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?

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

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

📌 discover results are NOT in your library. You must add them 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

🏗️ 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 with MCPTUBE_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). Prefer get_frame for 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.

Built with FastMCP · yt-dlp · ChromaDB · LiteLLM