tubeprobe
Allows exporting clean Markdown notes with video metadata and timestamped transcripts to Apple Notes.
Allows exporting clean Markdown notes with video metadata and timestamped transcripts to Notion.
Allows exporting clean Markdown notes with video metadata, chapters, and timestamped transcripts to an Obsidian vault.
Provides tools for YouTube research, including searching videos, retrieving video and channel metadata, transcripts, comments, playlists, related videos, trending videos, and live content.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
tubeprobe
Keyless, open-source YouTube research for humans and AI agents. One small CLI + a local MCP server: search, video & channel metadata, transcripts, comments, playlists, related videos, trending, live — plus optional speech-to-text with your engine and model, and optional export to your notes app.
No API key, no account, no hosted service. Runs on your machine; nothing is proxied through anyone's server.
Tiny core. Pure Python standard library + one bundled 0.7 MB JavaScript file + the official ~3 MB yt-dlp release. No ML libraries, no models, no
node_modules, zero required pip dependencies.Bring your own transcription. For videos without captions, plug in MacWhisper, whisper.cpp, mlx-whisper, faster-whisper, OpenAI Whisper, or any CLI — any model, any language. Off until you configure it.
Bring your own notes app. Save a clean Markdown note (metadata, chapters, timestamped transcript linking back to the video) to a folder, Obsidian, Notion, Apple Notes, a webhook, or any command. Off until you configure it.
Works with every MCP client: Cursor, Claude Desktop, Claude Code, Codex, Gemini CLI, and others.
Status: beta (0.1). Built on yt-dlp and YouTube.js, which do the hard work of speaking YouTube's internal web API. See Limitations.
Contents
How it compares · Install · Quickstart (CLI) · Use it from an AI agent (MCP) · Configuration · Transcription · Export to notes · Tools reference · Security · Limitations · Legal · Contributing
Related MCP server: youtube-connector-mcp
How it compares
tubeprobe | Hosted YouTube-research APIs / MCPs (paid) | YouTube Data API v3 | yt-dlp alone | |
Cost | Free, MIT | Subscription / credits | Free quota (10k units/day), then quota requests | Free |
API key / account | None | Required | Required (Google Cloud project) | None |
Where it runs | Your machine | Their servers (your queries go to them) | Your machine | |
Search, video, channel, playlist metadata | ✅ | ✅ | ✅ | Partial (no search filters, no suggest) |
Transcripts (manual + auto captions, translation) | ✅ | ✅ | ❌ (only your own videos) | ✅ (download only) |
Videos without captions | ✅ your own STT engine, any language | Varies / extra cost | ❌ | ❌ |
Comments + replies, community posts, hashtags, live, suggest | ✅ | Varies | Partial | Comments only |
Export to notes (Obsidian, Notion, Markdown, webhook…) | ✅ built in, opt-in | ❌ | ❌ | ❌ |
MCP server for AI agents | ✅ local (stdio) | ✅ (remote) | ❌ | ❌ |
Rate limits | YouTube's own per-IP throttling | Provider plan | Quota | YouTube's per-IP throttling |
Trade-off, honestly: a hosted service runs a fleet of IPs and absorbs YouTube's anti-bot measures for you. tubeprobe talks to YouTube from your own IP, so very heavy use (hundreds of transcript fetches in a few minutes) gets temporarily throttled. For personal research it's plenty; for bulk scraping it's the wrong tool (and see Legal).
Install
Requirements: Python ≥ 3.11 and Node.js ≥ 20 on PATH. Optional: ffmpeg (only for speech-to-text).
# 1. install the CLI (pick one)
uv tool install git+https://github.com/avalidurl/tubeprobe # or: pipx install git+https://github.com/avalidurl/tubeprobe
# 2. fetch the official yt-dlp release (~3 MB), pinned and SHA-256 verified
tubeprobe setup
# 3. check
tubeprobe status(Not on PyPI yet — install from GitHub as above.) Prefer pip-managed yt-dlp? Install
"tubeprobe[yt-dlp] @ git+https://github.com/avalidurl/tubeprobe" instead and skip tubeprobe setup.
Keep yt-dlp current — YouTube changes often: run tubeprobe setup again after upgrading tubeprobe.
Upgrade: re-run the install command with --reinstall (uv caches builds by version number, so plain --force
can reinstall the old code), e.g. uv tool install --reinstall git+https://github.com/avalidurl/tubeprobe.
From source:
git clone https://github.com/avalidurl/tubeprobe && cd tubeprobe
uv tool install --reinstall . # or: pip install .
tubeprobe setupInstall size (measured): a 0.2 MB wheel (0.8 MB installed, including the bundled bridge) + the 3 MB yt-dlp release = about 4 MB on disk. Speech-to-text engines and their models are separate and entirely your choice.
Quickstart (CLI)
Every command prints JSON, so it pipes nicely into jq.
tubeprobe search "espresso machine review" --type video --upload_date this_month --sort_by view_count
tubeprobe video dQw4w9WgXcQ --fields title,views,likes,published
tubeprobe transcript "https://youtu.be/dQw4w9WgXcQ" --language en --text_only
tubeprobe transcript dQw4w9WgXcQ --translate_to de # YouTube's machine translation
tubeprobe comments dQw4w9WgXcQ --sort new
tubeprobe channel @veritasium
tubeprobe tab @veritasium --tab shorts --limit 20
tubeprobe playlist PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI
tubeprobe trending --region GB
tubeprobe save dQw4w9WgXcQ # export to your configured notes app(s)
tubeprobe --help # all commandsUse it from an AI agent (MCP)
tubeprobe mcp speaks MCP over stdio (the default and recommended transport). Register it once per client.
If a client says it can't start the server, replace "tubeprobe" with the absolute path from which tubeprobe
(desktop apps don't inherit your shell's PATH).
{ "mcpServers": { "tubeprobe": { "command": "tubeprobe", "args": ["mcp"] } } }macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json
{ "mcpServers": { "tubeprobe": { "command": "tubeprobe", "args": ["mcp"] } } }GUI apps don't see your shell's PATH, so use the absolute path from which tubeprobe
(e.g. "/Users/you/.local/bin/tubeprobe"). tubeprobe itself also looks for node/ffmpeg in ~/.local/bin,
Homebrew, /usr/local/bin, Volta and nvm; set TUBEPROBE_NODE if yours lives elsewhere.
claude mcp add --scope user tubeprobe -- tubeprobe mcp[mcp_servers.tubeprobe]
command = "tubeprobe"
args = ["mcp"]{ "mcpServers": { "tubeprobe": { "command": "tubeprobe", "args": ["mcp"] } } }Then just ask: "Find the three most-viewed videos about sourdough from this month, read their transcripts and summarize the techniques — save each to my notes."
HTTP transport (opt-in, local only). tubeprobe mcp --http --port 8765 serves POST /mcp on 127.0.0.1 only
(never exposed to your network). Set TUBEPROBE_HTTP_TOKEN to require Authorization: Bearer <token>; requests with a
non-local Origin header are rejected (DNS-rebinding protection). Prefer stdio unless your client needs HTTP.
Configuration
Optional file: ~/.config/tubeprobe/config.toml (override with $TUBEPROBE_CONFIG). Start from
config.example.toml. Everything is off by default.
Environment variable | Meaning |
| Path to config.toml |
| Comma list overriding |
| Overrides |
|
|
| Response cache (default |
| Cache lifetime in seconds (default 3600) |
| Proxy URL passed to yt-dlp (e.g. |
| Optional Netscape |
| Where |
| Use a specific yt-dlp zipapp |
| Path to the |
| Bearer token for |
| Optional: lets |
Transcription (optional)
Most videos have captions and tubeprobe uses them (manual first, then auto-generated, any language, with optional
translation). Only for videos without captions does it fall back to speech-to-text — and only if you've configured
an engine. tubeprobe never ships, picks, or downloads a model. No language is assumed: set language to whatever your
model supports, or leave it empty for auto-detect, and override per call with --language.
[transcription]
engines = ["whisper-cpp"] # tried in order
language = "" # auto-detect
[transcription.whisper-cpp]
model = "~/models/ggml-large-v3-turbo.bin"Engine | Install (your choice of model) | Notes |
| MacWhisper ≥ 13 ( | Uses the app's models (Whisper / Parakeet). Check the app's "translate to English" setting is off if you want the original language. |
|
| Fast on CPU / Metal / CUDA |
|
| Apple Silicon. Downloads the model you name on first use. |
|
| faster-whisper (CTranslate2) |
|
| Reference implementation (PyTorch) |
| anything |
|
Requires ffmpeg. Audio is downloaded to a temp dir, converted to 16 kHz mono WAV, transcribed, and deleted.
tubeprobe status shows what's configured; tubeprobe stt <video> --engine X forces a specific engine.
Export to notes (optional)
Add one or more [[export.sinks]] to your config. Then tubeprobe save <video>, tubeprobe transcript <video> --save,
the MCP tool save_to_notes, or [export] auto = true to save on every transcript fetch.
[export]
auto = true
[[export.sinks]]
type = "obsidian"
vault = "~/Obsidian/MyVault"
folder = "sources/youtube/{channel_slug}"
filename = "{date}-{slug}"
frontmatter = { type = "source", created = "{today}" }
tags = ["youtube"]Sink types: markdown (any folder — Logseq, Foam, Zettlr, a git repo…), obsidian (+ optional link line in an
existing daily note), notion (database row; token from $NOTION_TOKEN), apple-notes (macOS), webhook
(POST JSON — n8n, Zapier, Make, your server; header values can reference ${ENV_VARS}), command (any program,
markdown on stdin, no shell). Full options are in config.example.toml.
Each note contains: YAML frontmatter (title, video_id, url, channel, published, duration, views, likes, comments,
transcript source/language, fetched-at, your extra keys and tags), chapters with timestamp links, the description, and
the transcript in ~1-minute paragraphs, each starting with a [mm:ss](https://youtu.be/ID?t=S) link.
Notes are idempotent per video id: saving again updates the same file (or on_existing = "skip"), keeps the
original created value, and preserves anything you write below the <!-- tubeprobe:end --> marker.
Folder/filename templates are sanitized — placeholder values are slugified and paths can't escape the sink directory.
Writing a new sink is ~20 lines: add def sink_<name>(cfg, md, note, fields) -> dict to tubeprobe/sinks.py and register it.
Tools reference
MCP tool | CLI | What it does |
|
| Search with filters: upload date, type, duration, sort, features (HD, 4K, subtitles, live, …), channel, region/lang, paging |
|
| Autocomplete suggestions |
|
| Videos for a #hashtag |
|
| Popular right now (official chart with |
|
| Live streams right now |
|
| Full metadata, chapters, tags, formats summary, |
|
| Up to 50 videos in parallel |
|
| Timestamped transcript; language/kind/translation; STT fallback; optional save |
|
| Up-next / related |
|
| Top or newest comments, paged |
|
| Replies to a comment |
|
| Channel details (subscribers, description, links, …) |
|
| Up to 50 channels |
|
| Channel videos / shorts / streams / playlists |
|
| Community posts |
|
| Playlist metadata + items, paged |
|
| Any YouTube URL / handle → canonical ids (+ start time) |
|
| Export a video (+ transcript) to configured sinks |
|
| Show configured engines and sinks |
Security
Local by default. stdio MCP transport; the optional HTTP transport binds to 127.0.0.1 only, supports a bearer token, rejects foreign
Origins and bodies over 1 MB.No shell, ever. External programs (STT engines,
commandsinks, ffmpeg, node) are run with argument lists, never through a shell, so titles/URLs can't inject commands.Validated inputs. Video ids, channel ids/handles, playlist ids and URLs are checked against strict patterns and YouTube host names before use; MCP arguments are type/enum/range-checked and unknown arguments are rejected.
Safe file writes. Note paths are built from slugified values and confined to the configured directory (path-traversal guard); writes are atomic.
Secrets stay out of config. Notion tokens come from env vars; webhook headers can reference
${ENV}.Supply chain. Zero required Python dependencies. The JS bridge is built from a locked
package-lock.json. yt-dlp is downloaded from its official GitHub release and verified against a pinned SHA-256. CI runs ruff (incl. bandit rules), tests,pip-audit, andnpm audit.No telemetry. tubeprobe only talks to YouTube (and to sinks/engines you configure).
Report vulnerabilities privately — see SECURITY.md.
Limitations
Per-IP throttling. YouTube rate-limits heavy use from one IP (HTTP 429 / "confirm you're not a bot"), especially for transcripts. tubeprobe caches responses and falls back to alternate endpoints for metadata, but bursts of many dozens of transcript requests can still pause for 5–10 minutes. Cloud/datacenter IPs are throttled far sooner than home connections.
Unofficial interfaces. yt-dlp and YouTube.js use YouTube's internal web API. When YouTube changes, update yt-dlp (
tubeprobe setup) and tubeprobe.Trending: YouTube retired its Trending page in 2025. Without
YOUTUBE_API_KEY,trendingis a proxy (fresh uploads ranked by views across configurable seed queries), not YouTube's chart.No age-restricted / members-only / private content by default.
TUBEPROBE_COOKIEScan pass a cookies file to yt-dlp, but logged-in automation can get an account flagged — if you use it, use a throwaway account and keep the file private.notionandapple-notessinks are newer and less battle-tested thanmarkdown/obsidian/webhook/command.
Legal & responsible use
tubeprobe is an independent project, not affiliated with or endorsed by YouTube or Google. It reads publicly available pages the same way a browser does, but YouTube's Terms of Service restrict automated access and downloading. You are responsible for how you use it. It's intended for personal research, accessibility, note-taking and education. Don't use it to mass-scrape, to redistribute other people's content, or to circumvent access controls; respect creators' copyright. Speech-to-text downloads audio temporarily to your machine and deletes it.
Contributing
Issues and PRs welcome — see CONTRIBUTING.md. New sinks and engines are deliberately small, self-contained functions.
License
MIT. Third-party components: THIRD_PARTY_NOTICES.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
YouTube for AI agents: transcripts, comments, video stats, channel monitor, Shorts captions.
Search YouTube videos, read transcripts and get public video information in your AI assistant.
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to search videos, read channels, browse playlists, fetch comments, and get transcripts from YouTube using the YouTube Data API v3 and InnerTube API for captions.2GPL 3.0
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to search videos, channels, and playlists, retrieve video metadata, transcripts, and comments via the YouTube Data API v3.46 PyPI68MIT
- AlicenseAqualityDmaintenanceEnables AI agents to search, watch, summarize, clip, and extract transcripts from YouTube videos, all without needing an API key or leaving the chat.968Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to search videos, retrieve transcripts and metadata, analyze channels, and access trending and engagement analytics for YouTube content.-