yt-gemini-mcp
Uses the Google Gemini API to analyze YouTube video content, with configurable models, resolution detail, transcripts, and bounded fallback behavior.
Enables analysis of public YouTube videos, including summaries, detailed notes, tutorials, key quotes, claim extraction, Q&A, and analysis of specific time ranges.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yt-gemini-mcp Could you watch this video and break down the step-by-step instructions for building a custom keyboard? [URL]"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Version: v5.0 | 2026-11-21 | Optional YouTube transcript you paste yourself; Claude asks before analyzing
yt-gemini-mcp
English | 繁體中文
A local MCP server that lets Claude (Claude Code / Claude Desktop) "watch" public YouTube videos through the Google Gemini API: summaries, detailed notes, step-by-step tutorials, key quotes, claim extraction, Q&A, and analysis of a specific time range.
Local stdio MCP server — opens no network ports
Exactly one read-only tool,
analyze_youtube; no file writes, no shell, no arbitrary HTTPYour API key lives only in Windows Credential Manager — never in files, environment variables, or Claude config
Bring your own Gemini API key (free to create in Google AI Studio)
Windows only for now; analysis output is in Traditional Chinese (see Limitations)
Security design
Risk | Mitigation |
API key leakage | Key stored only in Windows Credential Manager via |
Key left on screen or in shell history |
|
Key in logs or error messages | All logs go to stderr through a redacting formatter ( |
SSRF / abuse | Only |
Prompt injection | The Gemini system instruction says instructions inside the video must only be reported, never followed. Results are wrapped in |
Supply chain | Only three direct dependencies ( |
Quota / resources | Total time budget per call (70 s for chat, 240 s for code, including fallback); SDK auto-retry disabled in favour of a bounded model fallback (max 3) and at most one short retry per model on a fast 503; models whose daily quota is exhausted are skipped until reset; call limits (2 concurrent, 5 per minute, 100 per 24 h — excess calls are rejected); low media resolution by default; token usage logged (numbers only) |
Found a vulnerability? Please report it privately as described in SECURITY.md — do not open a public issue.
Related MCP server: youtube-mcp-server
Requirements
Windows 10/11, a normal (non-admin) user account
uv (manages Python for you)
A Gemini API key from Google AI Studio
Claude Code and/or Claude Desktop
Installation
1. Install uv
winget install --id=astral-sh.uv -e --source wingetOpen a new terminal afterwards so PATH is updated.
2. Clone and create the environment (installs the exact versions in uv.lock)
git clone https://github.com/hometraice/yt-gemini-mcp.gitcd yt-gemini-mcpuv sync --lockedBelow, <project-dir> means the full path of the cloned folder, e.g. C:\Users\<you>\yt-gemini-mcp.
Set your API key
Run this yourself in a terminal (never paste the key into a Claude chat):
uv run set_key.pyYou will be asked to paste the key twice; input is hidden. Then verify:
uv run set_key.py --checkYou should see [OK] for every model used in config.toml. --check only fetches model metadata and does not consume generation quota.
Replace the key: run
uv run set_key.pyagainDelete the key:
uv run set_key.py --delete
Recommended on the Google side: restrict the key to the Generative Language API in Google Cloud Console → Credentials. If you suspect a leak, delete the key in AI Studio, create a new one, and run set_key.py again.
Choosing a profile
You register the server once per Claude app and pick a profile for it. In plain terms:
You use… | Profile | What you get |
Claude Desktop chat, claude.ai on the web, or the mobile app (through Claude Desktop) |
| Fast answers (usually 5–20 s) from |
Claude Code (terminal, Code tab, Remote Control) |
| Deeper analysis from |
Rule of thumb: quick questions anywhere → chat; "I want everything in this video and can wait" → code in Claude Code.
Register with Claude Code
Run in Git Bash (Windows PowerShell 5.1 handles the -- separator differently):
claude mcp add yt-gemini --scope user -- uv --directory '<project-dir>' run --locked server.py --profile code--profile code uses the stronger gemini-3.8-flash model and a longer time budget (240 s). Note that the command contains no key — the server reads it from Credential Manager at runtime.
Check with claude mcp list.
Register with Claude Desktop
Find the full path of uv (Claude Desktop may not see your
PATH):(Get-Command uv).SourceIn Claude Desktop open Settings → Developer → Edit Config and add (use your own paths; escape backslashes):
{ "mcpServers": { "yt-gemini": { "command": "C:\\Users\\<you>\\...\\uv.exe", "args": [ "--directory", "<project-dir with escaped backslashes>", "run", "--locked", "server.py", "--profile", "chat" ] } } }Do not add an
envblock with your key — this file is plain text. Use thechatprofile here (fastflash-lite, 70 s budget): when Claude on the web or mobile calls a local MCP server through Claude Desktop, it gives up after roughly 80 seconds.Fully quit Claude Desktop (including the tray icon) and start it again.
Usage
Just ask Claude, for example:
"Summarize this video: https://youtu.be/xxxxxxxxxxx"
"What is discussed between 5:00 and 10:00?"
"What numbers are on the slide? Use high resolution."
"Turn this tutorial video into steps I can follow." (
tutorial)"Write detailed notes for this video." (
notes)
Tool parameters
Parameter | Type | Required | Description |
| string | yes | YouTube URL |
| see below | no | Analysis mode, default |
| string | no | A question or focus (max 2000 chars). In |
| int | no | Start time in seconds |
| int | no | End time in seconds (must be greater than |
|
| no | Frame resolution, default |
| string | no | The YouTube transcript you copied yourself (max 120,000 chars). Improves spelling of names and lets |
Adding a transcript (optional)
When you ask Claude to analyze a video without a transcript, Claude first asks whether you want to add one, or just analyze. To get the transcript:
Open the video on YouTube and click ...more under the video
Click Show transcript
Select all of the transcript, copy it, and paste it into the chat
Gemini still watches the video for what is on screen; the transcript is used for exact names and quotes. Where it disagrees with the audio, the result says so. Answer "just analyze" (or "don't ask again") to skip.
The server never fetches transcripts itself: unofficial scrapers break YouTube's terms and the official API only serves captions for your own videos
The transcript is treated as untrusted data, like the video: it is wrapped in tags with a random id and Gemini is told never to follow instructions inside it
Claude has to copy the transcript into the tool call, so for long videos paste only the part you care about. With
start/end, the server keeps only that range (plus 30 s on each side) based on the timestampsIt is sent to Google together with the video (free-tier data may be used by Google), so don't paste anything private
Modes
| Best for | Output |
| Getting the big picture | Structured summary |
| Capturing nearly everything | Detailed notes in 1–3 minute sections |
| How-to / coding videos | Followable steps; on-screen commands, code and prompts copied verbatim into code blocks; a list of things to verify against official docs |
| Citing the speaker | 5–15 key quotes with timestamps |
| Fact-checking | Factual claims, the evidence given, and verification priority |
Output always includes [mm:ss] timestamps and separates what was seen (【畫面】) from what was heard (【語音】); uncertain parts are marked.
Reading the last line of a result
The footer (outside the untrusted tags) tells you which model answered and why, e.g. 模型:gemini-3.5-flash-lite,chat 入口的主要模型 ("primary model of the chat profile"):
Primary model of the chat profile — expected: chat uses the fast
flash-litebecause of the ~80 s limit. Use Claude Code for deeper analysis.Fallback model — the primary model failed; the next line gives the reason (timeout, HTTP code, or daily quota exhausted).
Retried once — Gemini answered
503(overloaded) within a few seconds, so the server waited 1.5 s and tried the same model once more. It only does this when enough time is left, at most once per model.
When a call fails, the message says which kind of failure it was:
Message | Meaning | What to do |
Model temporarily overloaded (HTTP 503) | Google is short on capacity for this model | Try again in about a minute |
Exceeded Google's time limit (HTTP 504) | Gemini took too long on Google's side | Analyze a shorter range with |
No response within N seconds; stopped waiting | The server's own time budget ran out | In |
yt-gemini-mcp v…is the version currently loaded; if you still see an old version after updating, fully restart Claude Desktop.
Tips
Start with
summary, then dig into important parts withstart/end.For long videos or long outputs (
notes,tutorial), work in 5–10 minute segments.Use
detail="default"when the screen shows code, commands, or small text.
Configuration (config.toml)
Each entry point (profile) has its own models and limits; pick one with --profile (default chat).
Profile | Primary model | Fallback | Thinking level | Total / primary wait |
|
| none |
| 70 s / 35 s |
|
|
|
| 240 s / 150 s |
model,fallback_models— fallback is used on timeout, overload (5xx) or quota (429); max 3. Before falling back, a fast503gets one short retry on the same model (within that model's wait time)thinking_level—low/medium/hightimeout_seconds,attempt_timeout_seconds— total budget and how long to wait for the primary model[gemini] max_output_tokens— response length cap (default 16384)[limits]—max_concurrent(2),max_calls_per_minute(5),max_calls_per_day(100, rolling 24 h). Limits always apply, even if the section is missingtemperatureis not used (deprecated for Gemini 3 models); the server refuses to start if it is present
Gemini free tier notes (checked against Google's docs, 2026-11)
Quotas are per Google Cloud project, not per key; daily quotas reset at midnight Pacific Time
Per-model free-tier numbers are not listed in the docs — check the rate-limit page in AI Studio
YouTube input: max 8 hours of video per day on the free tier; public videos only; the feature is in preview
Free-tier content may be used by Google to improve its products — don't put secrets in
question
When Gemini returns a 429 whose error details clearly indicate a daily quota, the server remembers that model and skips it until the next reset (computed as 08:00 UTC; up to one hour late during daylight saving time). Anything ambiguous is treated as a normal 429. This state is in memory only.
Token usage is logged to stderr after each successful call: Gemini usage: model=… prompt=… output=… thoughts=… total=… (numbers only, no content).
Development
uv run python -m unittest -vUnit tests use mocks only — no network, no key. A live test (uses your key and a little quota; analyzes a 19-second public video) is opt-in:
$env:YT_GEMINI_LIVE_TEST = "1"; uv run python -m unittest tests.test_live -v; Remove-Item Env:YT_GEMINI_LIVE_TESTComparing two models (opt-in, uses quota)
tools/compare_models.py runs the same video and mode once on each of up to two models and records the time taken and token counts, to help you decide which model a profile should use:
uv run tools/compare_models.py "https://youtu.be/<id>" --mode summary --start 0 --end 300Without --yes-use-quota it only prints what it would do (dry run: no key read, no network). Add --yes-use-quota to actually call Gemini — each model uses one request of your quota (two if a fast 503 triggers the automatic retry). Only models listed in config.toml are accepted; by default it compares each profile's primary model. Results go to logs\compare-<timestamp>-<random>\ (git-ignored): one .md per model with Gemini's output wrapped in untrusted tags, a summary.json with timings and token counts, and run.log. Logs are written only to run.log, never to the terminal. The key is read from Credential Manager and never printed or written.
Project layout:
server.py MCP server entry point (the only tool: analyze_youtube)
set_key.py store / check / delete the API key
tools/ opt-in developer tools (compare_models.py)
config.toml non-secret settings: profiles, models, time budgets, call limits
yt_gemini/ internal modules (config, keystore, redaction, validation, gemini, quota, ratelimit, untrusted)
tests/ unit tests and the opt-in live test
SPEC.md design spec and threat model (Traditional Chinese)Dependencies: mcp 2.3.0 (MIT), google-genai 2.34.0 (Apache-2.0), keyring 25.7.0 (MIT). External services: Google Gemini API (receives the canonical video URL, your question and the system instruction; the key is sent in an HTTP header). Results appear in your Claude conversation.
See CONTRIBUTING.md before opening a pull request.
Limitations
Windows only (the key store is pinned to Windows Credential Manager on purpose)
Output language is Traditional Chinese (set in the system instruction in
yt_gemini/gemini.py)Public videos only, one video per call
gemini-3.8-flashis a preview model and is often overloaded (503/504);codefalls back toflash-litewhen that happensThe
chatprofile has no fallback model (there is no time for one within 70 s). An occasional503is expected; the server retries once automatically, and if it still fails, just ask againA timed-out request may still be processed (and counted) on Google's side
Developers have reported that with
start/endon YouTube URLs, audio may still be billed for the whole video
License
MIT. This project is not affiliated with or endorsed by Google, YouTube, or Anthropic. Use of the Gemini API is subject to the Gemini API Terms.
Available Tools
1 toolanalyze_youtubeARead-only
請 Gemini 觀看一支公開的 YouTube 影片,依 mode 產生分析,或回答 question。
回答使用繁體中文,附 [mm:ss] 時間戳,並區分【畫面】與【語音】來源。
只支援公開影片(私人、不公開影片無法分析)。
使用建議:
- 使用者沒有提供轉錄稿時,呼叫前先問一次要不要附上(步驟:影片頁面「顯示完整資訊」→「顯示轉錄稿」→ 全選複製
→ 貼回對話),或直接分析;使用者選直接分析就不要再問。轉錄稿要照抄使用者貼的文字放進 transcript;
分段分析時只放該段時間的部分。
- 先用 mode="summary" 掌握全貌,再針對重要段落用 start/end(可搭配 question 或其他 mode)深入。
- 教學、實作影片要學做法:mode="tutorial";畫面上有程式碼、指令或小字時加 detail="default"。
- 長影片(超過約 20 分鐘)或要 notes、tutorial 這類長輸出時,用 start/end 分段,每段 5–10 分鐘。
- 結果最後會註明實際使用的模型,以及它是這個使用入口的「主要模型」還是「備援模型」。
chat 入口(Claude Desktop 一般對話、網頁版、手機)因為約 80 秒的等待限制,主要模型就是較快的 flash-lite,
不是額度或錯誤造成的;需要更深入的分析,建議改在 Claude Code 使用(主要模型較強、時間較長)。
- 用了備援模型時內容較淺,最後一行會寫出原因(含 503 過載時自動重試 1 次的結果),重要細節可以稍後重試。
- 失敗訊息會區分:503 模型過載(約 1 分鐘後再試)、504 Google 端處理逾時(用 start/end 縮短範圍)、
本機等待逾時(chat 入口可改在 Claude Code 分析)。
- 結果最後一行若寫「今日額度已用完」,代表該模型要等每日重置(台灣時間約 16:00)才會再使用。
Inputs: url (required), end, mode, start, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool there is no cross-tool selection risk, so an agent cannot pick the wrong tool. The only ambiguity is internal: the mode values (summary/notes/tutorial/question) plus start/end/detail/transcript parameters overlap conceptually and require the long description to navigate.
The single name analyze_youtube follows a clear verb_noun snake_case pattern that matches its action precisely. No conventions are mixed because there is nothing else to conflict with.
A single tool is defensible for a narrow domain (analyze one YouTube video), and folding modes into parameters avoids tool sprawl. However, the tool is overloaded with many modes, retry/quota semantics, and multi-step workflow instructions, which is a lot of behavior behind one entry point.
Core analysis workflows (summary, notes, tutorial, question, segmented ranges) are covered, but there are notable gaps: no automatic transcript retrieval (the user must paste it), no playlist/channel or multi-video support, and no access to private/unlisted videos.
Maintenance
Related MCP Connectors
An MCP server that gives any LLM or agent clean YouTube transcripts on demand: a single video, a whole channel, or a playlist, plus AI cleanup of auto-generated captions. API-key auth, credit-based, same backend as the public v1 API. Get a free API key with 25 free credits at youtubetranscriptdownload.com/account.
Hosted YouTube MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Your YouTube library, in the AI tools you already use: Claude, ChatGPT, Cursor, any MCP client.
Real-time YouTube transcripts, comments, channels & video search MCP. Local npx or hosted OAuth.
Related MCP Servers
- AlicenseAqualityCmaintenanceA comprehensive MCP server that provides Claude AI with full access to YouTube content, including searchable transcripts, metadata, comments, and playlists. It uniquely supports capturing video screenshots and extracting audio clips for analysis across both local and remote platforms.523 npm3MIT
- AlicenseAqualityDmaintenanceA local stdio MCP server that gives Claude (or any MCP client) full programmatic control over a single YouTube channel, including video upload, channel management, comments, analytics, and more.46MIT
- AlicenseNot gradedqualityDmaintenanceA local MCP server that connects Claude to your YouTube channel, enabling video analysis, performance tracking, comment reading, and niche suggestions.ISC
- AlicenseNot gradedqualityDmaintenanceA local, read-only MCP server that provides Claude with private YouTube Analytics data—views, retention, traffic sources, demographics, revenue, and impressions/CTR—via authenticated Google APIs.MIT