Skip to content
Back to search

mcptube

Transform YouTube videos into a compounding knowledge base with transcripts, vision analysis, and agentic search. Works as an MCP server for Claude, Copilot & more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/0xchamin--mcptube/badge.svg)](/listings/0xchamin--mcptube)

HTML

<a href="/listings/0xchamin--mcptube"><img src="/api/listings/0xchamin--mcptube/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- **Python 3.12 or 3.13** - **ffmpeg** — required for frame extraction ([install guide](https://ffmpeg.org/download.html))

Recommended: pipx

pipx install mcptube --python python3.12

Alternative: pip

python3.12 -m venv venv
source venv/bin/activate
pip install mcptube

Verify installation

mcptube --help

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 719 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🎬 mcptube-vision
  2. **YouTube video knowledge engine — transcripts, vision, and persistent wiki.**
  3. [![PyPI](https://img.shields.io/pypi/v/mcptube)](https://pypi.org/project/mcptube/)
  4. [![Python](https://img.shields.io/pypi/pyversions/mcptube)](https://pypi.org/project/mcptube/)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  6. mcptube-vision transforms YouTube videos into a persistent, structured knowledge base using both transcripts and visual frame analysis. Built on the [Karpathy LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern: knowledge compounds with every video you add.
  7. > **Evolved from [mcptube](https://pypi.org/project/mcptube/) v0.1** — mcptube-vision replaces semantic chunk search with a persistent wiki that gets smarter with every video ingested.
  8. ---
  9. ## 🧠 How It Works
  10. Traditional video tools re-discover knowledge from scratch on every query. mcptube-vision is different:
  11. ```
  12. mcptube v0.1 mcptube-vision
  13. ┌─────────────────────┐ ┌─────────────────────────┐
  14. │ Query → vector search│ │ Video ingested → LLM │
  15. │ → raw chunks → LLM │ │ extracts knowledge → │
  16. │ → answer (from scratch│ │ wiki pages created → │
  17. │ every time) │ │ cross-references built │
  18. └─────────────────────┘ │ │
  19. │ Query → FTS5 + agent │
  20. │ → reasons over compiled │
  21. │ knowledge → answer │
  22. └─────────────────────────┘
  23. ```
  24. | | v0.1 (Video Search Engine) | vision (Video Knowledge Engine) |
  25. |---|---|---|
  26. | **On ingest** | Chunk transcript, embed in vector DB | LLM watches + reads, writes wiki pages |
  27. | **On query** | Find similar chunks | Agent reasons over compiled knowledge |
  28. | **Frames** | Timestamp or keyword extraction | Scene-change detection + vision model |
  29. | **Cross-video** | Re-search all chunks each time | Connections already in the wiki |
  30. | **Over time** | Library of isolated videos | Compounding knowledge base |
  31. ---
  32. ## 🏗️ Technical Architecture
  33. mcptube-vision is built around a core insight: **video knowledge should compound, not be re-discovered**. Every architectural decision flows from this principle.
  34. ### System Overview
  35. ```mermaid
  36. flowchart TD
  37. YT[YouTube URL] --> EXT[YouTubeExtractor\ntranscript + metadata]
  38. EXT --> FRAMES[SceneFrameExtractor\nffmpeg scene-change detection]
  39. FRAMES --> VISION[VisionDescriber\nLLM vision model]
  40. VISION --> WIKI_EXT[WikiExtractor\nLLM knowledge extraction]
  41. EXT --> WIKI_EXT
  42. WIKI_EXT --> WIKI_ENG[WikiEngine\nmerge + update]
  43. WIKI_ENG --> FILE[FileWikiRepository\nJSON pages on disk]
  44. WIKI_ENG --> FTS[SQLite FTS5\nsearch index]
  45. FILE --> AGENT[Ask Agent\nFTS5 → LLM reasoning]
  46. FTS --> AGENT
  47. FILE --> CLI[CLI / MCP Server]
  48. FTS --> CLI
  49. subgraph Ingestion Pipeline
  50. EXT
  51. FRAMES
  52. VISION
  53. WIKI_EXT
  54. end
  55. subgraph Knowledge Store
  56. WIKI_ENG
  57. FILE
  58. FTS
  59. end
  60. subgraph Retrieval
  61. AGENT
  62. end
  63. ```
  64. The system overview shows three distinct subsystems connected by a unidirectional data flow. The **Ingestion Pipeline** (left) transforms a raw YouTube URL into structured knowledge through four stages: transcript extraction, scene-change frame detection, vision-model description, and LLM-powered knowledge extraction. Each stage enriches the signal — raw video becomes text, text becomes typed knowledge objects.
  65. The **Knowledge Store** (center) is the persistent layer. The WikiEngine applies merge semantics — deciding whether to create new pages or append to existing ones — then writes JSON files to disk and updates the FTS5 search index in parallel. These two stores serve different access patterns: files for full-page reads and exports, FTS5 for sub-millisecond keyword retrieval.
  66. The **Retrieval** layer (right) combines both stores. The Ask Agent first narrows via FTS5, then loads full pages from disk, and finally reasons over candidates with structural awareness from the wiki TOC. The CLI and MCP Server sit alongside as thin presentation layers — they never contain business logic.
  67. ---
  68. ### Ingestion Flow
  69. ```mermaid
  70. sequenceDiagram
  71. participant User
  72. participant CLI
  73. participant YouTubeExtractor
  74. participant SceneFrameExtractor
  75. participant VisionDescriber
  76. participant WikiExtractor
  77. participant WikiEngine
  78. participant FileRepo
  79. participant FTS5
  80. User->>CLI: mcptube add <url>
  81. CLI->>YouTubeExtractor: fetch transcript + metadata
  82. YouTubeExtractor-->>CLI: segments, duration, channel
  83. CLI->>SceneFrameExtractor: extract scene frames (ffmpeg)
  84. SceneFrameExtractor-->>CLI: frame images (scene_000x.jpg)
  85. CLI->>VisionDescriber: describe frames (LLM vision)
  86. VisionDescriber-->>CLI: frame descriptions (prose)
  87. CLI->>WikiExtractor: extract knowledge\n(transcript + frame descriptions)
  88. WikiExtractor-->>CLI: entities, topics, concepts, video page
  89. CLI->>WikiEngine: merge into wiki
  90. WikiEngine->>FileRepo: write/update JSON pages\n(append entities, rewrite synthesis)
  91. WikiEngine->>FTS5: update search index
  92. FileRepo-->>WikiEngine: ✅
  93. FTS5-->>WikiEngine: ✅
  94. WikiEngine-->>CLI: wiki processed
  95. CLI-->>User: ✅ Added + Wiki: full_analysis
  96. ```
  97. The ingestion flow is a **write-once pipeline** — LLM-heavy at ingest time, but never repeated for the same video. This is the key cost tradeoff: invest tokens upfront to build compiled knowledge, so retrieval is cheap.
  98. The sequence shows two critical branching points. First, after transcript extraction, the pipeline forks into vision processing (scene frames → LLM vision descriptions) and feeds both streams into the WikiExtractor. This dual-signal approach means the LLM sees both what was *said* and what was *shown* — critical for content like coding tutorials or slide-based lectures where the transcript alone misses visual information.
  99. Second, the WikiEngine merge step is where knowledge compounding happens. Rather than blindly writing new pages, it checks for existing entities, topics, and concepts — appending new video contributions to existing pages and rewriting synthesis summaries. This is why ingesting video #10 makes the wiki smarter about videos #1–9 too: shared concepts get richer synthesis with each new source.
  100. The final FTS5 index update runs synchronously after the file write, ensuring search consistency. There is no eventual-consistency window — once `add_video` returns, all new knowledge is immediately searchable.
  101. ---
  102. ### Retrieval Flow
  103. ```mermaid
  104. sequenceDiagram
  105. participant User
  106. participant CLI
  107. participant FTS5
  108. participant FileRepo
  109. participant Agent
  110. User->>CLI: mcptube ask "What is RLHF?"
  111. CLI->>FTS5: keyword search (sanitized query)
  112. FTS5-->>CLI: candidate page slugs (ranked)
  113. CLI->>FileRepo: load candidate pages (JSON)
  114. FileRepo-->>CLI: wiki pages (entities, topics, concepts)
  115. CLI->>FileRepo: load wiki TOC
  116. FileRepo-->>CLI: table of contents (all page titles + types)
  117. CLI->>Agent: candidates + TOC + question
  118. Agent-->>CLI: reasoned answer with source citations
  119. CLI-->>User: answer + (source-slug) citations
  120. ```
  121. The retrieval flow is deliberately **two-stage** to balance cost and intelligence. The first stage — FTS5 keyword search — runs entirely locally with zero LLM tokens, narrowing thousands of wiki pages to a ranked handful in milliseconds. Query sanitization strips special characters (e.g. `?`, `!`) that would break FTS5 syntax, ensuring robustness for natural-language questions.
  122. The second stage loads two types of context for the agent: the **candidate pages** (full detail — summaries, contributions, entity references) and the **wiki TOC** (a compact structural map of all knowledge). The TOC is critical — it gives the agent awareness of what it *doesn't* know. Without it, the agent would hallucinate answers from weak matches. With it, the agent can reason: "The wiki has pages on RLHF and scaling laws, but nothing on quantum computing — so I should say I don't have that information."
  123. In CLI mode (BYOK), the agent is an LLM call that synthesizes the final answer with source citations. In MCP server mode (passthrough), this stage returns the raw candidates and TOC to the client — letting the client's own model (Copilot, Claude, Gemini) do the reasoning. This dual-mode design means the server never requires an API key when used via MCP.
  124. ---
  125. ### Subsystem Breakdown
  126. #### 1. Ingestion Pipeline
  127. **YouTubeExtractor** pulls transcript segments via `youtube-transcript-api` and video metadata via `yt-dlp`. Transcripts are chunked by natural segment boundaries, not fixed token windows — preserving semantic coherence.
  128. **SceneFrameExtractor** uses ffmpeg's perceptual scene-change filter (`select='gt(scene,{threshold})'`) rather than fixed-interval sampling. This is deliberate: fixed intervals waste tokens on static frames (slides held for 30s), while scene-change detection captures *transitions* — the moments of highest information density. The threshold (default `0.4`) is configurable.
  129. **VisionDescriber** sends detected frames to a vision-capable LLM (GPT-4o, Claude, Gemini — auto-detected via API key priority). Frame descriptions are plain prose, not structured JSON, to maximise the LLM's descriptive latitude.
  130. **Why this matters:** A transcript of a coding tutorial misses the code on screen. Scene-change vision capture recovers that signal without the token cost of dense fixed-interval sampling.
  131. ---
  132. #### 2. WikiEngine — The Novel Core ⭐
  133. Inspired by the [Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f), this is the most architecturally distinctive component.
  134. **WikiExtractor** takes the combined transcript + frame descriptions and prompts an LLM to extract four typed knowledge objects:
  135. | Type | Semantics | Update Policy |
  136. |------|-----------|---------------|
  137. | `video` | Immutable per-video summary + timestamps | Write-once |
  138. | `entity` | People, tools, companies | Append-only — new references added, never overwritten |
  139. | `topic` | Broad themes (e.g. "Scaling Laws") | Synthesis rewritten; per-video contributions immutable |
  140. | `concept` | Specific ideas (e.g. "RLHF") | Synthesis rewritten; per-video contributions immutable |
  141. **WikiEngine** handles merge semantics — when a new video references an existing entity or concept, it integrates the new evidence without destroying prior contributions. This is a **CRDT-like append model** for knowledge, not a vector store replacement index.
  142. **Why this matters:** Vector stores are retrieval indexes — they don't synthesize. Two videos about "attention mechanisms" produce two isolated chunks. The WikiEngine merges them into a single `concept-attention-mechanisms` page with a synthesis that evolves as evidence accumulates. Knowledge compounds.
  143. Version history is maintained for all non-immutable pages — every synthesis rewrite is snapshotted, enabling full auditability.
  144. ---
  145. #### 3. Storage Layer
  146. **FileWikiRepository** stores wiki pages as JSON on disk, one file per page. Chosen over a document DB deliberately:
  147. - Human-readable and git-diffable
  148. - Trivially exportable to markdown/HTML
  149. - Schema evolution without migrations
  150. **SQLite FTS5** maintains a parallel search index over page titles, tags, and content. Chosen over a vector store because:
  151. - Zero embedding cost at query time
  152. - Deterministic, auditable results
  153. - Sub-millisecond latency at thousands of pages
  154. **Why not ChromaDB/Pinecone?** At wiki scale, BM25-style keyword search over *compiled knowledge pages* outperforms semantic similarity over *raw chunks* — the wiki pages are already semantically rich by construction.
  155. ---
  156. #### 4. Hybrid Retrieval Agent ⭐
  157. The `ask` command uses a deliberate two-stage pattern:
  158. 1. **FTS5 keyword search** — narrows the full wiki to a small candidate set (milliseconds, zero LLM cost)
  159. 2. **LLM agent** — receives candidates + the wiki table of contents, reasons about relevance, synthesizes a grounded answer with source citations
  160. **Why this matters over RAG:** Standard RAG retrieves chunks and generates. The agent here retrieves *compiled knowledge pages* and *reasons*. The wiki TOC gives the agent structural awareness of what knowledge exists — enabling it to correctly say "I don't have information about X" rather than hallucinating from weak chunk matches.
  161. ---
  162. #### 5. MCP Server
  163. Exposes all subsystems as tools consumable by any MCP-compatible client. Report and synthesis tools use a **passthrough pattern** — returning structured data for the client's own LLM to analyse, rather than making a second LLM call server-side. This avoids double-billing and lets the client model apply its own reasoning style.
  164. ---
  165. ### Key Design Decisions
  166. | Decision | Alternative Considered | Reason |
  167. |----------|----------------------|--------|
  168. | Scene-change frame extraction | Fixed-interval sampling | Higher signal/token ratio |
  169. | Wiki knowledge model | Vector store chunks | Knowledge compounds; no re-discovery per query |
  170. | FTS5 retrieval | Embedding similarity | Compiled wiki pages are already semantic |
  171. | File-based wiki storage | SQLite/document DB | Human-readable, git-diffable, zero migrations |
  172. | Append-only entity updates | Full rewrite | Source attribution preserved; full auditability |
  173. | Passthrough MCP reports | Server-side LLM | Avoids double-billing; client model reasons |
  174. ---
  175. ## ✨ Features
  176. | Feature | CLI | MCP Server |
  177. |---------|:---:|:----------:|
  178. | Add/remove YouTube videos | ✅ | ✅ |
  179. | Wiki knowledge base (auto-built) | ✅ | ✅ |
  180. | Scene-change frame extraction + vision analysis | ✅ | ✅ |
  181. | Full-text wiki search (FTS5) | ✅ | ✅ |
  182. | Agentic Q&A over wiki | ✅ | ✅ |
  183. | Browse wiki pages (entities, topics, concepts) | ✅ | ✅ |
  184. | Wiki version history | ✅ | ✅ |
  185. | Wiki export (markdown, HTML) | ✅ | — |
  186. | Illustrated reports (single & cross-video) | ✅ (BYOK) | ✅ (passthrough) |
  187. | YouTube discovery + clustering | ✅ (BYOK) | ✅ |
  188. | Cross-video synthesis | ✅ (BYOK) | ✅ (passthrough) |
  189. | Text-only processing mode | ✅ | ✅ |
  190. **BYOK** = Bring Your Own Key (Anthropic, OpenAI, or Google)
  191. **Passthrough** = The MCP client's own LLM does the analysis
  192. ---
  193. ## 📦 Installation
  194. ### Prerequisites
  195. - **Python 3.12 or 3.13**
  196. - **ffmpeg** — required for frame extraction ([install guide](https://ffmpeg.org/download.html))
  197. ### Recommended: pipx
  198. ```bash
  199. pipx install mcptube --python python3.12
  200. ```
  201. ### Alternative: pip
  202. ```bash
  203. python3.12 -m venv venv
  204. source venv/bin/activate
  205. pip install mcptube
  206. ```
  207. ### Verify installation
  208. ```bash
  209. mcptube --help
  210. ```
  211. ---
  212. ## 🚀 Quick Start
  213. ```bash
  214. # 1. Add a video (builds wiki automatically)
  215. mcptube add "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  216. # 2. Add with text-only processing (cheaper, faster)
  217. mcptube add "https://www.youtube.com/watch?v=abc123" --text-only
  218. # 3. Browse the wiki
  219. mcptube wiki list
  220. mcptube wiki show "video-dQw4w9WgXcQ"
  221. # 4. Search the knowledge base
  222. mcptube search "main topic"
  223. # 5. Ask a question (agentic retrieval over wiki)
  224. mcptube ask "What are the key ideas discussed?"
  225. # 6. View the table of contents
  226. mcptube wiki toc
  227. ```
  228. > 💡 **Always wrap multi-word arguments in double quotes.**
  229. ---
  230. ## 📖 CLI Reference
  231. ### Library Management
  232. | Command | Description | Example |
  233. |---------|-------------|---------|
  234. | `mcptube add "<url>"` | Ingest video + build wiki (full analysis) | `mcptube add "https://youtu.be/dQw4w9WgXcQ"` |
  235. | `mcptube add "<url>" --text-only` | Ingest without vision processing | `mcptube add "https://youtu.be/abc" --text-only` |
  236. | `mcptube list` | List all videos with tags | `mcptube list` |
  237. | `mcptube info <query>` | Show full video details (transcript, chapters) | `mcptube info 1` |
  238. | `mcptube remove <query>` | Remove video + clean wiki references | `mcptube remove 1` |
  239. > `<query>` can be a video index number, video ID, or partial title.
  240. ---
  241. ### Wiki Knowledge Base
  242. | Command | Description | Example |
  243. |---------|-------------|---------|
  244. | `mcptube wiki list` | Browse all wiki pages | `mcptube wiki list` |
  245. | `mcptube wiki list --type <type>` | Filter by type: `video`, `entity`, `topic`, `concept` | `mcptube wiki list --type concept` |
  246. | `mcptube wiki list --tag <tag>` | Filter by tag | `mcptube wiki list --tag AI` |
  247. | `mcptube wiki show <slug>` | Read a specific wiki page in full | `mcptube wiki show "entity-openai"` |
  248. | `mcptube wiki search "<query>"` | Full-text search across all wiki pages | `mcptube wiki search "attention"` |
  249. | `mcptube wiki toc` | Table of contents (all pages, compact) | `mcptube wiki toc` |
  250. | `mcptube wiki history <slug>` | Version history for a wiki page | `mcptube wiki history "topic-ml"` |
  251. | `mcptube wiki export` | Export all pages as markdown (default) | `mcptube wiki export -o wiki_export/` |
  252. | `mcptube wiki export --format html` | Export all pages as single HTML file | `mcptube wiki export --format html -o wiki.html` |
  253. | `mcptube wiki export --page <slug>` | Export a single page | `mcptube wiki export --page "entity-openai" -o openai.md` |
  254. ---
  255. ### Search & Ask
  256. | Command | Description | Example |
  257. |---------|-------------|---------|
  258. | `mcptube search "<query>"` | Full-text search, returns page list | `mcptube search "transformers"` |
  259. | `mcptube ask "<question>"` | Agentic Q&A over wiki (BYOK) | `mcptube ask "What is self-attention?"` |
  260. ---
  261. ### Frames
  262. | Command | Description | Example |
  263. |---------|-------------|---------|
  264. | `mcptube frame <query> <timestamp>` | Extract frame at exact timestamp (seconds) | `mcptube frame 1 30.5` |
  265. | `mcptube frame-query <query> "<description>"` | Extract frame by transcript match | `mcptube frame-query 1 "when they show the diagram"` |
  266. ---
  267. ### Analysis & Reports (BYOK)
  268. | Command | Description | Example |
  269. |---------|-------------|---------|
  270. | `mcptube classify <query>` | LLM classify + tag a video | `mcptube classify 1` |
  271. | `mcptube report <query>` | Generate illustrated report for one video | `mcptube report 1` |
  272. | `mcptube report <query> --focus "<topic>"` | Guide report with a focus query | `mcptube report 1 --focus "RLHF"` |
  273. | `mcptube report <query> --format html -o <file>` | Save report as HTML | `mcptube report 1 --format html -o report.html` |
  274. | `mcptube report-query "<topic>"` | Cross-video report on a topic | `mcptube report-query "scaling laws"` |
  275. | `mcptube report-query "<topic>" --tag <tag>` | Cross-video report filtered by tag | `mcptube report-query "AI" --tag research` |
  276. | `mcptube report-query "<topic>" -o <file>` | Save cross-video report | `mcptube report-query "AI" --format html -o report.html` |
  277. | `mcptube synthesize-cmd "<topic>" -v <id> -v <id>` | Cross-video theme synthesis | `mcptube synthesize-cmd "RLHF" -v id1 -v id2` |
  278. | `mcptube synthesize-cmd "<topic>" -v <id> --format html -o <file>` | Save synthesis as HTML | `mcptube synthesize-cmd "AI" -v id1 --format html -o out.html` |
  279. | `mcptube discover "<topic>"` | Search YouTube, cluster results (no ingest) | `mcptube discover "prompt engineering"` |
  280. ---
  281. ### Server
  282. | Command | Description |
  283. |---------|-------------|
  284. | `mcptube serve` | Start MCP server over HTTP (default `127.0.0.1:9093`) |
  285. | `mcptube serve --stdio` | Start MCP server over stdio (for Claude Desktop) |
  286. | `mcptube serve --host <host> --port <port>` | Custom host/port |
  287. | `mcptube serve --reload` | Hot-reload mode for development |
  288. ---
  289. ## 🧩 Wiki Page Types
  290. When you ingest a video, mcptube-vision builds four types of wiki pages:
  291. | Page Type | Created From | Update Policy |
  292. |-----------|-------------|---------------|
  293. | **Video** | Each ingested video | Write-once (immutable) |
  294. | **Entity** | People, companies, tools mentioned | Append-only (new references added) |
  295. | **Topic** | Broad themes (e.g., "Machine Learning") | Synthesis rewritten, per-video contributions immutable |
  296. | **Concept** | Specific ideas (e.g., "Scaling Laws") | Synthesis rewritten, per-video contributions immutable |
  297. **Principle:** Raw source content (what was said/shown in each video) is never modified. Only synthesis summaries evolve as new videos are added. Version history is maintained for all changes.
  298. ---
  299. ## 🔍 How Search Works (Hybrid Retrieval)
  300. mcptube-vision uses a two-step hybrid approach:
  301. 1. **SQLite FTS5** — keyword search narrows thousands of wiki pages to a handful of candidates (milliseconds, zero LLM cost)
  302. 2. **LLM Agent** — reads candidates + wiki table of contents, reasons about relevance, synthesizes an answer
  303. This gives you the speed of keyword search with the intelligence of an LLM agent.
  304. ---
  305. ## 👁️ Vision Pipeline
  306. When you ingest a video without `--text-only`, mcptube-vision:
  307. 1. Extracts key frames using **ffmpeg scene-change detection** (`select='gt(scene,0.4)'`)
  308. 2. Sends frames to a **vision-capable LLM** (GPT-4o, Claude, Gemini) for description
  309. 3. Combines frame descriptions with transcript in the knowledge extraction pass
  310. This captures visual content (slides, code, diagrams, demos) that transcripts alone miss.
  311. ---
  312. ## 🔌 MCP Client Setup
  313. mcptube exposes 25+ MCP tools via two transports:
  314. | Transport | How it works | Used by |
  315. |-----------|-------------|---------|
  316. | **Streamable HTTP** (`/mcp`) | Client connects to a running mcptube server | VS Code, Claude Code, Cursor, Windsurf, Codex, Gemini CLI |
  317. | **stdio** | MCP client spawns `mcptube` as a child process | Claude Desktop |
  318. > ℹ️ The MCP server is currently available for **local use only**. You must run `mcptube serve` locally or let the client spawn it.
  319. ---
  320. ### VS Code + GitHub Copilot ✅ Tested
  321. Open `Cmd+Shift+P` → **MCP: Open User Configuration** and add:
  322. ```json
  323. {
  324. "servers": {
  325. "mcptube": {
  326. "url": "http://127.0.0.1:9093/mcp"
  327. }
  328. }
  329. }
  330. ```
  331. Then start the server in a terminal:
  332. ```bash
  333. mcptube serve
  334. ```
  335. ---
  336. ### Claude Code ✅ Tested
  337. ```bash
  338. claude mcp add mcptube --transport http http://127.0.0.1:9093/mcp
  339. ```
  340. Then start the server in a separate terminal:
  341. ```bash
  342. mcptube serve
  343. ```
  344. ---
  345. ### Claude Desktop
  346. Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
  347. **If installed via `pipx` (recommended):**
  348. ```json
  349. {
  350. "mcpServers": {
  351. "mcptube": {
  352. "command": "mcptube",
  353. "args": ["serve", "--stdio"]
  354. }
  355. }
  356. }
  357. ```
  358. **If installed in a virtual environment:**
  359. ```json
  360. {
  361. "mcpServers": {
  362. "mcptube": {
  363. "command": "/full/path/to/.venv/bin/mcptube",
  364. "args": ["serve", "--stdio"]
  365. }
  366. }
  367. }
  368. ```
  369. No separate server needed — Claude Desktop spawns the process automatically.
  370. ---
  371. ### Cursor
  372. Create or edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-scoped):
  373. ```json
  374. {
  375. "mcpServers": {
  376. "mcptube": {
  377. "url": "http://127.0.0.1:9093/mcp"
  378. }
  379. }
  380. }
  381. ```
  382. Then start the server:
  383. ```bash
  384. mcptube serve
  385. ```
  386. ---
  387. ### Windsurf
  388. Edit `~/.codeium/windsurf/mcp_config.json`:
  389. ```json
  390. {
  391. "mcpServers": {
  392. "mcptube": {
  393. "serverUrl": "http://127.0.0.1:9093/mcp"
  394. }
  395. }
  396. }
  397. ```
  398. Then start the server:
  399. ```bash
  400. mcptube serve
  401. ```
  402. ---
  403. ### OpenAI Codex
  404. Edit `~/.codex/config.toml`:
  405. ```toml
  406. [mcp_servers.mcptube]
  407. url = "http://127.0.0.1:9093/mcp"
  408. ```
  409. Then start the server:
  410. ```bash
  411. mcptube serve
  412. ```
  413. ---
  414. ### Gemini CLI
  415. Edit `~/.gemini/settings.json`:
  416. ```json
  417. {
  418. "mcpServers": {
  419. "mcptube": {
  420. "httpUrl": "http://127.0.0.1:9093/mcp"
  421. }
  422. }
  423. }
  424. ```
  425. Then start the server:
  426. ```bash
  427. mcptube serve
  428. ```
  429. ---
  430. ### Verify Connection
  431. Once connected, ask your MCP client:
  432. > use mcptube. list all videos in my library
  433. It should call the `list_videos` tool and return results.
  434. ### MCP Tools
  435. | Tool | Description |
  436. |------|-------------|
  437. | `add_video` | Ingest video + build wiki |
  438. | `list_videos` | List library |
  439. | `remove_video` | Remove video + clean wiki |
  440. | `wiki_list` | Browse wiki pages |
  441. | `wiki_show` | Read a wiki page |
  442. | `wiki_search` | Full-text search |
  443. | `wiki_toc` | Table of contents |
  444. | `wiki_ask` | Agentic Q&A |
  445. | `wiki_history` | Version history |
  446. | `get_frame` | Extract frame (inline image) |
  447. | `get_frame_by_query` | Frame by transcript match |
  448. | `classify_video` | Get metadata for classification |
  449. | `generate_report` | Get data for single-video report |
  450. | `generate_report_from_query` | Get data for cross-video report |
  451. | `synthesize` | Get data for theme synthesis |
  452. | `discover_videos` | Search YouTube |
  453. | `ask_video` | Single-video Q&A data |
  454. | `ask_videos` | Multi-video Q&A data |
  455. ---
  456. ## ⚙️ Configuration
  457. All settings can be overridden via environment variables prefixed with `MCPTUBE_`:
  458. | Setting | Default | Env Var |
  459. |---------|---------|---------|
  460. | Data directory | `~/.mcptube` | `MCPTUBE_DATA_DIR` |
  461. | Server host | `127.0.0.1` | `MCPTUBE_HOST` |
  462. | Server port | `9093` | `MCPTUBE_PORT` |
  463. | Default LLM model | `gpt-4o` | `MCPTUBE_DEFAULT_MODEL` |
  464. ### BYOK API Keys
  465. Set one or more to enable LLM features:
  466. ```bash
  467. export ANTHROPIC_API_KEY="sk-ant-..."
  468. export OPENAI_API_KEY="sk-..."
  469. export GOOGLE_API_KEY="AI..."
  470. ```
  471. Auto-detection priority: Anthropic → OpenAI → Google.
  472. ---
  473. ## 📁 Data Layout
  474. ```
  475. ~/.mcptube/
  476. ├── mcptube.db # Video metadata (SQLite)
  477. ├── wiki.db # FTS5 search index (SQLite)
  478. ├── wiki/
  479. │ ├── video/ # Video pages (JSON)
  480. │ ├── entity/ # Entity pages (JSON)
  481. │ ├── topic/ # Topic pages (JSON)
  482. │ ├── concept/ # Concept pages (JSON)
  483. │ └── _history/ # Version history
  484. └── frames/
  485. ├── <id>_<ts>.jpg # Single extracted frames
  486. └── <id>_scenes/ # Scene-change frames + metadata
  487. ```
  488. ---
  489. ## 🧪 Development
  490. ```bash
  491. git clone https://github.com/0xchamin/mcptube.git
  492. cd mcptube
  493. git checkout vision
  494. python3.12 -m venv venv
  495. source venv/bin/activate
  496. pip install -e ".[dev]"
  497. pytest
  498. ```
  499. ---
  500. ## 🗺️ Roadmap
  501. - [x] Wiki knowledge engine (entities, topics, concepts)
  502. - [x] Scene-change frame extraction + vision analysis
  503. - [x] Hybrid retrieval (FTS5 + agentic)
  504. - [x] CLI + MCP server
  505. - [ ] Playlist/series support
  506. - [ ] Web app with early access sign-up
  507. - [ ] Token-based payment integration
  508. ---
  509. ## 📄 License
  510. MIT — see [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.