search_youtube
Read-only
Search YouTube for videos, channels, or playlists on any topic. Returns up to 50 results with metadata for topic-based discovery.
Instructions
Search YouTube globally for videos, channels, or playlists on any topic. Returns up to 50 results with metadata. Use this for topic-based discovery when the user has not specified a channel — for searching within a known channel use search_channel_videos instead.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query (same syntax as YouTube's search bar, e.g. 'rust async tutorial', 'lex fridman dario amodei'). | |
| type | No | Search type: 'video', 'channel', or 'playlist'. Default: 'video'. | |
| limit | No | Max results (1-50, default 20). |
Implementation Reference
- src/index.js:79-102 (schema)Input schema for search_youtube tool: expects 'q' (string, required), optional 'type' (video/channel/playlist), optional 'limit' (1-50).
inputSchema: { type: "object", properties: { q: { type: "string", description: "Search query (same syntax as YouTube's search bar, e.g. 'rust async tutorial', 'lex fridman dario amodei').", minLength: 1, }, type: { type: "string", description: "Search type: 'video', 'channel', or 'playlist'. Default: 'video'.", enum: ["video", "channel", "playlist"], }, limit: { type: "number", description: "Max results (1-50, default 20).", minimum: 1, maximum: 50, }, }, required: ["q"], }, - src/index.js:74-76 (registration)Registration of the search_youtube tool in the TOOLS array with name, description, and annotations.
{ name: "search_youtube", description: - src/index.js:408-427 (handler)The callUpstream function handles all tool calls including search_youtube by forwarding to the upstream MCP server at SubDownload with Bearer token auth.
async function callUpstream(name, args) { if (!API_KEY) { throw new Error( "SUBDOWNLOAD_API_KEY env var is not set. Get one at https://subdownload.com/account, then run with -e SUBDOWNLOAD_API_KEY=<your-key>." ); } const res = await fetch(UPSTREAM_URL, { method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json, text/event-stream", Authorization: `Bearer ${API_KEY}`, }, body: JSON.stringify({ jsonrpc: "2.0", id: Date.now(), method: "tools/call", params: { name, arguments: args }, }), }); - src/index.js:36-53 (helper)ANN.YT_READ annotation hints used by search_youtube indicating read-only, non-idempotent, open-world (public data changes over time).
YT_READ: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true, }, // ASR job creation — coalesces on (video, lang) within cache TTL ASR_START: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true, }, // ASR poll — hits our backend only, status changes over time ASR_POLL: { readOnlyHint: true, destructiveHint: false, idempotentHint: false,