Skip to main content
Glama
Sign In
YouTube Research MCP

YouTube Research MCP

by jindratilk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Search YouTube

youtube_search
Read-onlyIdempotent

Search YouTube videos across multiple queries and languages, returning merged results with transcript highlights showing where each video discusses your topic, plus timestamped links.

Instructions

Search YouTube videos and get back ready-to-use results with transcript highlights: the passages where each video actually talks about your topic, with timestamped links.

Best for: finding videos on a topic, finding what creators say about something, collecting examples (hooks, claims, tutorials) across many videos. Returns: one merged, de-duplicated list across all queries. Each video has metadata (channel, views, date, duration, views/day), YouTube's matched snippet and key moments, plus transcript highlights for the top results.

Query tips:

  • Send several queries in ONE call to cover the topic: synonyms, angles and languages, e.g. ["AI productivity workflow", "how I use AI to save time at work", {"query": "productividad con IA", "hl": "es", "gl": "ES"}].

  • Write queries the way a creator would title the video, not as keyword soup.

  • Use filters (uploaded, publishedAfter, minViews, duration, shorts) instead of asking for more results.

  • If highlights are not enough, call youtube_fetch on the best videos (it can return only a time range, e.g. the first 30 s for a hook, or only passages matching a query).

Input Schema

NameRequiredDescriptionDefault
sortNorelevance (default), views (server-side), or date: newest first among the fetched results; YouTube dropped server-side date sort, so pair it with uploaded.
limitNoResults per query before merging (default 10, max 50).
shortsNoDefault exclude.
queriesYes1–12 queries, run in one call and merged. Strings, or {query, hl, gl} for a language/region-specific query.
durationNoServer-side: short <4 min, medium 4–20 min, long >20 min.
minViewsNo
uploadedNoServer-side upload-date window. Prefer this over publishedAfter when it fits.
highlightsNoHow many top results get transcript highlights (default 5, 0 = off, max 25). Each downloads one transcript; YouTube rate-limits transcripts per IP, so spend them where they matter.
captionsOnlyNoOnly videos with subtitles/CC (server-side filter).
highlightQueryNoWhat to highlight in transcripts, if different from the search queries (e.g. search 'AI productivity', highlight 'biggest mistake').
maxDurationSecNo
minDurationSecNo
publishedAfterNoYYYY-MM-DD or YYYY-MM. Applied after search on YouTube's relative dates ('3 weeks ago'), so it is approximate (±1 unit).
publishedBeforeNoYYYY-MM-DD or YYYY-MM, approximate like publishedAfter.
transcriptLangsNoPreferred transcript languages in order, e.g. ['es','en']. Default: the video's original language.
highlightsPerVideoNoPassages per video (default 3, max 8).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds crucial behavioral context beyond that: merged de-duplicated results across queries, transcript highlights only for top results (rate-limit aware, default 5), approximate date filtering, and the note that highlights cost a transcript download per video due to YouTube rate limits. This is rich operational detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return value, then structured as 'Best for', 'Returns', and 'Query tips'. Every section is useful, though the query tips section is slightly long. Overall efficient and scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter search tool with no output schema, the description provides enough context to call it correctly: it explains result merging, highlight mechanics, rate-limit implications, and when to use youtube_fetch instead. The only gap is that the return shape (fields like views/day, key moments) is described in prose rather than schema, but that's adequate. An agent has what it needs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 81%, so the schema carries most parameter documentation. The description adds value by explaining the query array can mix strings and objects with hl/gl for localization, and by suggesting highlightQuery can differ from search queries. It doesn't explain every parameter (e.g., no details on sort or transcriptLangs), but the schema handles those adequately at 81% coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search) and resource (YouTube videos), and uniquely distinguishes itself from siblings by emphasizing transcript highlights and timestamped links. An agent can immediately tell this is the broad discovery tool vs. youtube_fetch for deep retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly lists what it's best for (topic finding, creator claims, example collection), provides concrete query construction tips, and names the alternative (youtube_fetch) with the exact condition to switch. Covers when to use filters instead of more results.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools