Skip to content
Back to search

yt-gemini-mcp

Local MCP server that lets Claude analyze public YouTube videos through the Gemini API (Windows & macOS, bring your own key)

Safety scan

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

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hometraice--yt-gemini-mcp/badge.svg)](/listings/hometraice--yt-gemini-mcp)

HTML

<a href="/listings/hometraice--yt-gemini-mcp"><img src="/api/listings/hometraice--yt-gemini-mcp/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.

**1. Install uv**

Windows (PowerShell):

winget install --id=astral-sh.uv -e --source winget

macOS (Terminal, with [Homebrew](https://brew.sh)):

brew install uv

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` or `/Users/<you>/yt-gemini-mcp`.

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 · 332 lines
  1. > Version: v8.2 | 2026-11-22 | When a transcript is worth pasting; changing models when Google retires one; other MCP clients
  2. # yt-gemini-mcp
  3. English | [繁體中文](README.zh-TW.md)
  4. 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.
  5. - Local **stdio** MCP server — opens **no network ports**
  6. - Exactly one read-only tool, `analyze_youtube`; no file writes, no shell, no arbitrary HTTP
  7. - Your API key lives **only in your OS key store** (Windows Credential Manager or macOS Keychain) — never in files, environment variables, or Claude config
  8. - Bring your **own** Gemini API key (free to create in Google AI Studio)
  9. - **Windows**, plus **macOS (experimental)**; output in **Traditional Chinese or English** (set `output_language` in `config.toml`)
  10. ---
  11. ## Security design
  12. | Risk | Mitigation |
  13. |---|---|
  14. | API key leakage | Key stored only in the OS key store via `keyring` (service `yt-gemini-mcp`, user `gemini`), pinned per platform: WinVault on Windows, Keychain on macOS; other platforms are refused, never a plaintext fallback. No `.env`, no environment variables. The server refuses to start if `config.toml` contains anything that looks like a key |
  15. | 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 |
  16. | 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 |
  17. | 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>` |
  18. | 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 |
  19. | 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 |
  20. | 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) |
  21. Found a vulnerability? Please report it privately as described in [SECURITY.md](SECURITY.md) — do not open a public issue.
  22. ---
  23. ## Requirements
  24. - Windows 10/11, or macOS (experimental — see below); a normal (non-admin) user account
  25. - [Git](https://git-scm.com/downloads)
  26. - [uv](https://docs.astral.sh/uv/) (manages Python for you)
  27. - A Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey)
  28. - Claude Code and/or Claude Desktop
  29. **Other MCP clients:** any AI tool that supports local stdio MCP servers can try connecting to it, but it has only been fully tested and tuned with Claude Desktop and Claude Code. The transcript question relies on Claude following the server's instructions (clickable options, then calling again); other clients may not, and may only ever get the "add a transcript?" note for each new video. If you use another client, set `ask_for_transcript = false` in `config.toml`.
  30. ## Installation
  31. **1. Install uv**
  32. Windows (PowerShell):
  33. ```powershell
  34. winget install --id=astral-sh.uv -e --source winget
  35. ```
  36. macOS (Terminal, with [Homebrew](https://brew.sh)):
  37. ```bash
  38. brew install uv
  39. ```
  40. Open a **new** terminal afterwards so `PATH` is updated.
  41. **2. Clone and create the environment** (installs the exact versions in `uv.lock`)
  42. ```powershell
  43. git clone https://github.com/hometraice/yt-gemini-mcp.git
  44. ```
  45. ```powershell
  46. cd yt-gemini-mcp
  47. ```
  48. ```powershell
  49. uv sync --locked
  50. ```
  51. Below, `<project-dir>` means the full path of the cloned folder, e.g. `C:\Users\<you>\yt-gemini-mcp` or `/Users/<you>/yt-gemini-mcp`.
  52. ## Set your API key
  53. Run this **yourself** in a terminal (never paste the key into a Claude chat):
  54. ```powershell
  55. uv run set_key.py
  56. ```
  57. You will be asked to paste the key twice; input is hidden. Then verify:
  58. ```powershell
  59. uv run set_key.py --check
  60. ```
  61. You should see `[OK]` for every model used in `config.toml`. `--check` only fetches model metadata and does not consume generation quota.
  62. On macOS the key goes into your login Keychain. The first time the server reads it, macOS may ask whether to allow access — the requesting program is the Python that uv manages for this project.
  63. - Replace the key: run `uv run set_key.py` again
  64. - Delete the key: `uv run set_key.py --delete`
  65. **Recommended on the Google side:** restrict the key to the `Generative Language API` in [Google Cloud Console → Credentials](https://console.cloud.google.com/apis/credentials). If you suspect a leak, delete the key in [AI Studio](https://aistudio.google.com/apikey), create a new one, and run `set_key.py` again.
  66. ## Choosing a profile
  67. You register the server once per Claude app and pick a **profile** for it. In plain terms:
  68. | You use… | Profile | What you get |
  69. |---|---|---|
  70. | 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 |
  71. | 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 |
  72. Rule of thumb: quick questions anywhere → `chat`; "I want everything in this video and can wait" → `code` in Claude Code.
  73. ## Register with Claude Code
  74. On Windows run this in **Git Bash** (Windows PowerShell 5.1 handles the `--` separator differently); on macOS use Terminal:
  75. ```bash
  76. claude mcp add yt-gemini --scope user -- uv --directory '<project-dir>' run --locked server.py --profile code
  77. ```
  78. `--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 the OS key store at runtime.
  79. Check with `claude mcp list`.
  80. ## Register with Claude Desktop
  81. 1. Find the full path of uv (Claude Desktop may not see your `PATH`):
  82. ```powershell
  83. (Get-Command uv).Source
  84. ```
  85. On macOS: `which uv` (usually `/opt/homebrew/bin/uv`).
  86. 2. In Claude Desktop open **Settings → Developer → Edit Config** and add (use your own paths; on Windows escape backslashes):
  87. ```json
  88. {
  89. "mcpServers": {
  90. "yt-gemini": {
  91. "command": "C:\\Users\\<you>\\...\\uv.exe",
  92. "args": [
  93. "--directory", "<project-dir with escaped backslashes>",
  94. "run", "--locked", "server.py", "--profile", "chat"
  95. ]
  96. }
  97. }
  98. }
  99. ```
  100. On macOS the same block works with plain paths, e.g. `"command": "/opt/homebrew/bin/uv"` and `"--directory", "/Users/<you>/yt-gemini-mcp"`.
  101. 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.
  102. 3. Fully quit Claude Desktop (including the tray icon) and start it again.
  103. ---
  104. ## Usage
  105. Just ask Claude, for example:
  106. - "Summarize this video: https://youtu.be/xxxxxxxxxxx"
  107. - "What is discussed between 5:00 and 10:00?"
  108. - "What numbers are on the slide? Use high resolution."
  109. - "Turn this tutorial video into steps I can follow." (`tutorial`)
  110. - "Write detailed notes for this video." (`notes`)
  111. ### Tool parameters
  112. | Parameter | Type | Required | Description |
  113. |---|---|---|---|
  114. | `url` | string | yes | YouTube URL |
  115. | `mode` | see below | no | Analysis mode, default `summary` |
  116. | `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 |
  117. | `start` | int | no | Start time in seconds |
  118. | `end` | int | no | End time in seconds (must be greater than `start`) |
  119. | `detail` | `"low"` \| `"default"` | no | Frame resolution, default `low` (cheaper); use `default` for small on-screen text |
  120. | `transcript` | string | no | The YouTube transcript you copied yourself (max 120,000 chars). Improves spelling of names and lets `quotes` cite the exact words |
  121. | `skip_transcript` | bool | no | Set by Claude when you chose to analyze without a transcript |
  122. ### Adding a transcript (optional)
  123. The first time you analyze a video without a transcript, the server does not call Gemini yet (this uses no quota). If your Claude app can show clickable options, Claude asks you with two buttons: **Paste transcript** or **Just analyze** (tested: Claude Desktop chat and the Code tab both show them). In an app without clickable options, Claude does not ask in text; it analyzes right away and the result ends with a tip about adding a transcript. Each video is checked only once. To get the transcript:
  124. 1. Open the video on YouTube and click **...more** under the video
  125. 2. Click **Show transcript**
  126. 3. Select all of the transcript, copy it, and paste it into the chat
  127. When is it worth it?
  128. | Paste a transcript | Just send the link |
  129. |---|---|
  130. | You want exact quotes (`quotes` mode) | You only want the gist (`summary`) |
  131. | Many names, products or technical terms | Mostly visual videos: demos, scenery, gameplay |
  132. | Talk-heavy videos: interviews, lectures, podcasts | Short videos, or the video has no transcript |
  133. 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. To turn the question off entirely, set `ask_for_transcript = false` in `config.toml`; results without a transcript then end with a one-line tip instead.
  134. - The server never fetches transcripts itself: unofficial scrapers break YouTube's terms and the official API only serves captions for your own videos
  135. - 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
  136. - 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
  137. - It is sent to Google together with the video (free-tier data may be used by Google), so don't paste anything private
  138. ### Modes
  139. | `mode` | Best for | Output |
  140. |---|---|---|
  141. | `summary` | Getting the big picture | Structured summary |
  142. | `notes` | Capturing nearly everything | Detailed notes in 1–3 minute sections |
  143. | `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 |
  144. | `quotes` | Citing the speaker | 5–15 key quotes with timestamps |
  145. | `claims` | Fact-checking | Factual claims, the evidence given, and verification priority |
  146. Output always includes `[mm:ss]` timestamps and separates what was **seen** (【畫面】) from what was **heard** (【語音】); uncertain parts are marked.
  147. ### Reading the last line of a result
  148. 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"):
  149. - **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.
  150. - **Fallback model** — the primary model failed; the next line gives the reason (timeout, HTTP code, or daily quota exhausted).
  151. - **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.
  152. When a call fails, the message says which kind of failure it was:
  153. | Message | Meaning | What to do |
  154. |---|---|---|
  155. | Model temporarily overloaded (HTTP 503) | Google is short on capacity for this model | Try again in about a minute |
  156. | 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"` |
  157. | 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 |
  158. - `yt-gemini-mcp v…` is the version currently loaded; if you still see an old version after updating, fully restart Claude Desktop. Claude is asked to repeat this footer line at the end of its reply; if it does not, expand the tool call in the Claude app to see the raw result.
  159. ### Tips
  160. - Start with `summary`, then dig into important parts with `start`/`end`.
  161. - For long videos or long outputs (`notes`, `tutorial`), work in 5–10 minute segments.
  162. - Use `detail="default"` when the screen shows code, commands, or small text.
  163. ---
  164. ## Configuration (`config.toml`)
  165. Each entry point (profile) has its own models and limits; pick one with `--profile` (default `chat`).
  166. | Profile | Primary model | Fallback | Thinking level | Total / primary wait |
  167. |---|---|---|---|---|
  168. | `chat` | `gemini-3.5-flash-lite` | none | `low` | 70 s / 35 s |
  169. | `code` | `gemini-3.8-flash` | `gemini-3.5-flash-lite` | `medium` | 240 s / 150 s |
  170. - `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)
  171. - `thinking_level` — `low` / `medium` / `high`
  172. - `timeout_seconds`, `attempt_timeout_seconds` — total budget and how long to wait for the primary model
  173. - `[gemini] output_language` — `"zh-TW"` (Traditional Chinese, default) or `"en"` (English). Controls Gemini's answer and the messages the server returns to Claude (footer, errors). The descriptions Claude reads (tool and parameter descriptions, server instructions) are always in English; Claude still replies in your language
  174. - `[gemini] ask_for_transcript` — `true` (default) or `false`. When true, the first analysis of each video without a transcript first asks you whether to add one
  175. - `[gemini] max_output_tokens` — response length cap (default 16384)
  176. - `[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
  177. - `temperature` is not used (deprecated for Gemini 3 models); the server refuses to start if it is present
  178. ### When Google renames or retires a model
  179. Model IDs live only in `config.toml`, so switching models needs no code change:
  180. 1. If a model has been retired, calls fail with "Model not found … Check that the model IDs in config.toml are currently available"
  181. 2. Pick a current model from Google's [model list](https://aistudio.google.com/docs/models) (retirement dates are on the [deprecations page](https://aistudio.google.com/docs/deprecations)) and replace `model` / `fallback_models` in the profile
  182. 3. Run `uv run set_key.py --check` — it confirms every model in `config.toml` exists, without using generation quota
  183. 4. Fully restart Claude Desktop (Claude Code picks it up in a new session)
  184. If a future model rejects `thinking_level`, remove that line from the profile to use the model's default. A code change would only be needed if Google changes the API itself.
  185. ### Gemini free tier notes (checked against Google's docs, 2026-11)
  186. - Quotas are per Google Cloud **project**, not per key; daily quotas reset at midnight Pacific Time
  187. - Per-model free-tier numbers are not listed in the docs — check the rate-limit page in [AI Studio](https://aistudio.google.com)
  188. - YouTube input: max 8 hours of video per day on the free tier; public videos only; the feature is in preview
  189. - Free-tier content may be used by Google to improve its products — don't put secrets in `question`
  190. 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.
  191. Token usage is logged to stderr after each successful call: `Gemini usage: model=… prompt=… output=… thoughts=… total=…` (numbers only, no content).
  192. ---
  193. ## Development
  194. ```powershell
  195. uv run python -m unittest -v
  196. ```
  197. 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:
  198. ```powershell
  199. $env:YT_GEMINI_LIVE_TEST = "1"; uv run python -m unittest tests.test_live -v; Remove-Item Env:YT_GEMINI_LIVE_TEST
  200. ```
  201. ### Comparing two models (opt-in, uses quota)
  202. `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:
  203. ```powershell
  204. uv run tools/compare_models.py "https://youtu.be/<id>" --mode summary --start 0 --end 300
  205. ```
  206. 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 the OS key store and never printed or written.
  207. Project layout:
  208. ```
  209. server.py MCP server entry point (the only tool: analyze_youtube)
  210. set_key.py store / check / delete the API key
  211. tools/ opt-in developer tools (compare_models.py)
  212. config.toml non-secret settings: profiles, models, time budgets, call limits
  213. yt_gemini/ internal modules (config, keystore, messages, redaction, validation, gemini, quota, ratelimit, untrusted)
  214. tests/ unit tests and the opt-in live test
  215. SPEC.md design spec and threat model (Traditional Chinese)
  216. ```
  217. Dependencies: [`mcp`](https://pypi.org/project/mcp/) 2.3.0 (MIT), [`google-genai`](https://pypi.org/project/google-genai/) 2.34.0 (Apache-2.0), [`keyring`](https://pypi.org/project/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.
  218. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
  219. ## Limitations
  220. - Windows and macOS only. **macOS support is experimental**: unit tests run on macOS in CI, but Keychain access has not yet been verified on a real Mac — please report how it goes. Linux is not supported yet (there is no pinned secure key store, and the server never falls back to a plaintext file)
  221. - Output languages: Traditional Chinese and English. Error messages about `config.toml` itself are in Chinese, because they can occur before the language setting is read
  222. - Public videos only, one video per call
  223. - `gemini-3.8-flash` is a preview model and is often overloaded (503/504); `code` falls back to `flash-lite` when that happens
  224. - 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
  225. - A timed-out request may still be processed (and counted) on Google's side
  226. - Developers have reported that with `start`/`end` on YouTube URLs, audio may still be billed for the whole video
  227. ## License
  228. [MIT](LICENSE). 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](https://ai.google.dev/gemini-api/terms).

Ratings and comments

Sign in to rate this skill.

Sign in

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