Skip to main content
Glama

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 HTTP

  • Your 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 keyring (service yt-gemini-mcp, user gemini), pinned to the WinVault backend. No .env, no environment variables. The server refuses to start if config.toml contains anything that looks like a key

Key left on screen or in shell history

set_key.py uses getpass (hidden input); refuses command-line arguments and piped input; aborts if the terminal cannot hide input

Key in logs or error messages

All logs go to stderr through a redacting formatter (AIza…, ?key=, x-goog-api-key, and the actual key in use); errors are fixed, human-readable messages with no stack traces

SSRF / abuse

Only youtube.com/watch?v=, youtu.be/, youtube.com/shorts/, m.youtube.com/watch?v= are accepted; exact host allowlist; 11-character video ID; the URL sent to Gemini is always rebuilt as https://www.youtube.com/watch?v=<ID>

Prompt injection

The Gemini system instruction says instructions inside the video must only be reported, never followed. Results are wrapped in <untrusted_video_analysis> tags whose opening and closing tags carry a per-call random id, so video content cannot forge the closing tag; tag-like text in the content (including full-width and invisible characters) is neutralized. Tutorial mode adds a "review before running" notice. Raw upstream error text is never returned to Claude

Supply chain

Only three direct dependencies (mcp, google-genai, keyring), pinned with ==, locked with hashes in uv.lock, started with --locked; exclude-newer avoids freshly published releases

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

  • Git

  • 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 winget

Open 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.git
cd yt-gemini-mcp
uv sync --locked

Below, <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.py

You will be asked to paste the key twice; input is hidden. Then verify:

uv run set_key.py --check

You 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.py again

  • Delete 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)

chat

Fast answers (usually 5–20 s) from gemini-3.5-flash-lite. These apps give up after about 80 s, so chat always finishes within 70 s

Claude Code (terminal, Code tab, Remote Control)

code

Deeper analysis from gemini-3.8-flash (often 1–3 minutes), with flash-lite as fallback. Best for long videos, tutorials and detailed notes

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

  1. Find the full path of uv (Claude Desktop may not see your PATH):

    (Get-Command uv).Source
  2. In 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 env block with your key — this file is plain text. Use the chat profile here (fast flash-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.

  3. 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

url

string

yes

YouTube URL

mode

see below

no

Analysis mode, default summary

question

string

no

A question or focus (max 2000 chars). In summary mode only the question is answered; other modes keep their format and focus on it

start

int

no

Start time in seconds

end

int

no

End time in seconds (must be greater than start)

detail

"low" | "default"

no

Frame resolution, default low (cheaper); use default for small on-screen text

transcript

string

no

The YouTube transcript you copied yourself (max 120,000 chars). Improves spelling of names and lets quotes cite the exact words

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:

  1. Open the video on YouTube and click ...more under the video

  2. Click Show transcript

  3. 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 timestamps

  • It is sent to Google together with the video (free-tier data may be used by Google), so don't paste anything private

Modes

mode

Best for

Output

summary

Getting the big picture

Structured summary

notes

Capturing nearly everything

Detailed notes in 1–3 minute sections

tutorial

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

quotes

Citing the speaker

5–15 key quotes with timestamps

claims

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-lite because 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 start/end; keep detail="low"

No response within N seconds; stopped waiting

The server's own time budget ran out

In chat, try again or switch to Claude Code (code, longer budget); split long videos

  • 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 with start/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

chat

gemini-3.5-flash-lite

none

low

70 s / 35 s

code

gemini-3.8-flash

gemini-3.5-flash-lite

medium

240 s / 150 s

  • model, fallback_models — fallback is used on timeout, overload (5xx) or quota (429); max 3. Before falling back, a fast 503 gets one short retry on the same model (within that model's wait time)

  • thinking_level — low / medium / high

  • timeout_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 missing

  • temperature is 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 -v

Unit 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_TEST

Comparing 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 300

Without --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-flash is a preview model and is often overloaded (503/504); code falls back to flash-lite when that happens

  • The chat profile has no fallback model (there is no time for one within 70 s). An occasional 503 is expected; the server retries once automatically, and if it still fails, just ask again

  • A timed-out request may still be processed (and counted) on Google's side

  • Developers have reported that with start/end on 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 tool
analyze_youtubeA
Read-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

    A4.5/5.0

    Scored across 1 tool

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A 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.
      5
      23 npm
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      46
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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