Skip to main content
Glama
Sign In
YouTube MCP

YouTube MCP

by pratikgh0se
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

youtube_search

Read-only

Search public YouTube videos by query and filter results by date, duration, channel, region, language, or safe-search settings.

Instructions

Search public YouTube videos (100 quota units per call). Optional filters: order, publishedAfter/publishedBefore (RFC 3339), videoDuration, channelId, regionCode, relevanceLanguage, safeSearch, pageToken.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "youtube_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
orderNoSort order: relevance, date, viewCount, rating or title.
queryYesSearch text to look for on YouTube.
channelIdNoRestrict results to this channel ID (UC...).
pageTokenNoPage token from the nextPageToken of a previous response, to fetch the next page.
maxResultsNoMaximum number of items to return, 1-50; omit to use the tool default.
regionCodeNoTwo-letter ISO 3166-1 region code, e.g. US.
safeSearchNoSafe-search filtering level: none, moderate or strict.
videoDurationNoFilter by video length: any, short, medium or long.
publishedAfterNoOnly return results published at or after this RFC 3339 timestamp.
publishedBeforeNoOnly return results published before this RFC 3339 timestamp.
relevanceLanguageNoPrefer results in this language code, e.g. en or zh-Hans.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv0.3.1
    • addedInput schema / properties / channelId / description
      Added value: +"Restrict results to this channel ID (UC...)."
    • addedInput schema / properties / maxResults / description
      Added value: +"Maximum number of items to return, 1-50; omit to use the tool default."
    • addedInput schema / properties / order / description
      Added value: +"Sort order: relevance, date, viewCount, rating or title."
    • addedInput schema / properties / pageToken / description
      Added value: +"Page token from the nextPageToken of a previous response, to fetch the next page."
    • addedInput schema / properties / publishedAfter / description
      Added value: +"Only return results published at or after this RFC 3339 timestamp."
    • addedInput schema / properties / publishedBefore / description
      Added value: +"Only return results published before this RFC 3339 timestamp."
    • addedInput schema / properties / query / description
      Added value: +"Search text to look for on YouTube."
    • addedInput schema / properties / regionCode / description
      Added value: +"Two-letter ISO 3166-1 region code, e.g. US."
    • addedInput schema / properties / relevanceLanguage / description
      Added value: +"Prefer results in this language code, e.g. en or zh-Hans."
    • addedInput schema / properties / safeSearch / description
      Added value: +"Safe-search filtering level: none, moderate or strict."
    • addedInput schema / properties / videoDuration / description
      Added value: +"Filter by video length: any, short, medium or long."
  2. Changed9 schema fields changedv0.3.0
    • addedInput schema / properties / channelId
      Added value: +{
+  "minLength": 1,
+  "type": "string"
+}
    • addedInput schema / properties / order
      Added value: +{
+  "enum": [
+    "relevance",
+    "date",
+    "viewCount",
+    "rating",
+    "title"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / pageToken
      Added value: +{
+  "minLength": 1,
+  "type": "string"
+}
    • addedInput schema / properties / publishedAfter
      Added value: +{
+  "format": "date-time",
+  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+  "type": "string"
+}
    • addedInput schema / properties / publishedBefore
      Added value: +{
+  "format": "date-time",
+  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+  "type": "string"
+}
    • addedInput schema / properties / regionCode
      Added value: +{
+  "pattern": "^[A-Za-z]{2}$",
+  "type": "string"
+}
    • addedInput schema / properties / relevanceLanguage
      Added value: +{
+  "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$",
+  "type": "string"
+}
    • addedInput schema / properties / safeSearch
      Added value: +{
+  "enum": [
+    "none",
+    "moderate",
+    "strict"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / videoDuration
      Added value: +{
+  "enum": [
+    "any",
+    "short",
+    "medium",
+    "long"
+  ],
+  "type": "string"
+}
  3. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

readOnlyHint=true already declares the safety profile, so the description's main added value is the 100-quota-unit cost disclosure, which no structured field carries and which materially affects call strategy. It stops short of noting what happens when quota is exhausted or how many items a default page returns.

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

Conciseness5/5

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

Two sentences, front-loaded with the action and its cost, followed by a compact filter list. Every token carries information and nothing is repeated.

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 read-only, fully schema-documented search tool with no output schema, the description covers what the tool does and its cost. The remaining gap is minimal — default page size and quota-failure behavior — which an agent would only learn by calling.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents every parameter including the enums, RFC 3339 date formats and the maxResults range. The description merely enumerates the filter names and repeats the RFC 3339 note, adding no syntax, interaction, or default-value information beyond structured data. Baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource ("Search public YouTube videos") with a scope qualifier ("public") that separates it from owned-content tools like youtube_list_owned_videos or youtube_list_channel_videos. It doesn't explicitly name which sibling to prefer for channel-scoped or trending content, but the verb alone makes the distinction legible.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: the quota cost signals this is an expensive call, but there is no explicit "when to use this instead of youtube_trending / youtube_list_channel_videos" routing, nor any note about when to add channelId versus using the channel-listing tools. The agent must infer the choice.

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