MCP integration
The Model Context Protocol lets your chat client call our MCP server directly. Once installed, you can ask Claude, ChatGPT, or Grok to search YouTube, check video details, read transcripts and comments, or start transcript collections without leaving the conversation.
Endpoint
A single Streamable HTTP endpoint serves every chat client:
https://api.youtubevideotranscript.io/mcpAuthentication
Two auth methods, same endpoint. Which one you use depends on what your client supports. See the per-client install guide for the exact path.
- API key (
yvt_live_*): paste into clients that accept a custom Bearer header. Used by Claude Code, its IDE integrations, and OpenAI’s Responses API. For other clients, use the authentication method their setup UI exposes. - OAuth 2.1: for clients whose UI only accepts an OAuth connector. Used by Claude.ai web, Claude Desktop, and ChatGPT’s consumer Apps & Connectors. The chat client discovers our authorization server, opens a consent page on
api.youtubevideotranscript.io, and you click Allow. No client_id pasting. Claude identifies itself with a metadata document Anthropic hosts. The server also supports Dynamic Client Registration for clients configured to use it. PKCE is required.
Tools exposed
| Tool | What it does | Cost |
|---|---|---|
get_transcript | Fetch the transcript for a single YouTube video. Accepts a full URL or an 11-character video ID. Optional language code. Optional format parameter (see below) controls the output shape. Optional include_comments appends the first page of top comments in the same call, so the model can cover both what was said and how people reacted. A nonempty comments page costs 1 additional credit. If comments fail or there is no credit left for them, the transcript is still returned with a comments error. | 1 credit for the transcript. Only with include_comments: true: +1 for the first page of top comments (usually about 20), if nonempty. Comments are off by default. |
get_video_info | Metadata for one video without fetching its transcript: title, channel, unrounded view count from the lookup, duration, description, keywords, and the list of caption tracks, so the model can tell whether a transcript exists and in which languages before spending a credit. A listed track does not guarantee a later fetch succeeds.include_dates adds the exact publish date, like count and category at the cost of a second upstream lookup, still with zero credit cost. See the dates and null-field contract. | Free |
list_channel_videos | Page through a channel's long-form videos, excluding Shorts. Returns one page plus a continuation token. Page size is set by YouTube and varies, so do not hard-code it. The first page also carries the channel’s rounded video count and subscriber text, as shown on YouTube. Each video carries its relative publish date and view count. | Free |
list_playlist_videos | Same as channel listing but for playlists. | Free |
search_youtube | Keyword search across YouTube. Returns about 20 results per page plus a continuation token. Narrow to videos, channels, or playlists, sort by relevance, date, views, or rating, and filter videos by upload date or length. Each result carries the id the other tools take, so the model can go from a search straight to a transcript, a channel listing, or a playlist listing. | Free |
get_video_comments | The public comments on a video, about 20 per page, top or newest first. Each comment with replies carries a token that walks its reply thread, and the first page reports the total count. Videos with comments turned off return a clear error. Failed fetches and empty pages are not charged. | 1 credit per nonempty page, usually about 20 top-level comments. YouTube controls the size; reply pages can be smaller and cost the same 1 credit when nonempty. |
search_channel_videos | Keyword search inside one channel, about 30 videos per page with a continuation token. The way to find what a specific channel has said about a topic without paging through every upload. | Free |
list_channel_playlists | The public playlists a channel curates, with item counts, so the model can work on one slice of a channel instead of every upload. Auto-generated lists the server cannot fetch are omitted. | Free |
get_channel_video_count | Exact number of long-form videos on a channel, Shorts excluded. Costs an extra upstream request, so the model is told to call it only when the exact figure matters, such as sizing a bulk job. | Free |
create_bulk_job | Collect transcripts from a channel, playlist, or video as a background job. Paid plans only, within the same per-plan caps as the REST API. Returns a link to the job in the web app, where the finished transcripts download as a ZIP under the same Google account that authorized the connector. Optional include_comments adds one Top page per successful transcript, saved as separate JSON files in the ZIP. | 1 credit per video; 2 reserved with comments. Unused credits refunded. |
list_jobs | The account’s recent bulk jobs, newest first, from any surface. How the model finds a job id it was not handed. | Free |
get_job | Status and progress of a bulk job, plus its web app link. | Free |
list_job_videos | Per-video results of a bulk job. Can include the completed transcripts and saved comments using include_transcript and include_comments, without paying again. | Free |
get_usage | Plan, credits used, total, and remaining for the current billing period. Lets the model check the budget before a large fetch. | Free |
Parameters and pagination
All tool inputs are JSON objects. Names use underscores, unlike some website request fields. Tokens are opaque; do not move them between unrelated tools. With a continuation, repeat required inputs even when the token carries their original values.
| Name | Type | Description |
|---|---|---|
get_transcript | object | Required url. Optional language, format (text by default; timestamps or json), include_comments (false). |
get_video_info | object | Required url. Optional include_dates (false). |
list_channel_videos / list_playlist_videos | object | Required url on every page. Optional continuation. |
search_youtube | object | Required query (1 to 200 characters). Optional type (all by default; video, channel, playlist), sort_by (relevance, date, views, rating), upload_date (hour, today, week, month, year), duration (short, medium, long), continuation. Filters are retained in the token. |
search_channel_videos | object | Required url and query on every page. Optional continuation. New queries must start without a token. |
get_video_comments | object | Required url on every page. Optional sort (top or newest), continuation. Use a reply_continuation as continuation to open replies. Sort is ignored on continuation pages. |
list_channel_playlists / get_channel_video_count | object | Required channel url, @handle, or UC... ID. Count can be null if unavailable. |
create_bulk_job | object | Required url. Optional format (txt, srt, json, csv, docx, markdown; default txt) and include_comments (false). No idempotency-key parameter. |
get_job | object | Required job_id (UUID). Returns kind, status, counters, message, and a website URL. |
list_job_videos | object | Required job_id. Optional status (pending, processing, completed, failed), cursor, limit (default 50, maximum 200), include_transcript and include_comments. Either include flag caps the actual page at 10 videos. |
list_jobs | object | Optional limit (default 10, maximum 50) and cursor (UUID from next_cursor). Returns total, jobs, next_cursor; jobs are newest first within the last 100 days. |
get_usage | object | No parameters. Legacy transcripts_* response names count shared credits, including comments and active reservations. |
Search results use the public result types; comments use the public comment fields. Search/listing tools return continuation; job tools return next_cursor. Null means no next page. An exact full final list_jobs page may be followed by an empty page.
Example tool inputs
{
"name": "search_channel_videos",
"arguments": { "url": "@mkbhd", "query": "iphone review" }
}{
"name": "get_transcript",
"arguments": {
"url": "dQw4w9WgXcQ",
"format": "timestamps",
"include_comments": true
}
}Transcript output formats
get_transcript accepts an optional format parameter so the model can pick the shape that matches what the user actually asked for. Token cost varies a lot.
format | Output | When to use |
|---|---|---|
text (default) | Title and Author lines when metadata is available, then prose with all segments joined, no timestamps. | Summaries, Q&A about content, theme extraction, sentiment, fact-checking. Cheapest token cost. |
timestamps | The same optional header, then one segment per line as [mm:ss] text (auto [hh:mm:ss] for videos over an hour). | Citation, identifying clips for highlights or memes, suggesting cut points, building chapter lists, any task anchored to time positions. |
json | Full structured JSON with metadata, language, and per-segment objects. | Raw transcript data, programmatic post-processing, anything that needs every field. |
The MCP structuredContent response field is populated only when format="json". For text and timestamps, only the plain text block is sent, so MCP clients that surface structured content to the model don’t accidentally pull in the full JSON.
With include_comments: true, JSON output adds comments: { total, rows } on success or comments_error if comments cannot be returned. Text formats append the sample or its error after the transcript. This convenience sample has no reply tokens; use get_video_comments to page comments or replies.
Bulk submission is not the REST contract
Starter allows 500 videos per job and 1 active job; Pro allows 2,000 and 2; Business allows 10,000 and 3. Free cannot create MCP bulk jobs. For a channel, the tool reserves up front and returns status: "resolving", channel_total, and the selected total_videos. Coverage is the smaller of the channel count, plan cap, and what the balance can reserve (2 credits per video with comments). Playlist jobs enumerate first and reject insufficient balance or an oversized source.
Each call can create a new job. After a lost response, check list_jobs before resubmitting. REST POST /jobs instead requires an Idempotency-Key, enumerates before charging, and rejects oversized channels instead of clipping them. Neither behavior has changed.
Poll get_job until completed, failed, or canceled; resolving, pending, and processing are nonterminal. The initial non-channel creation response uses queued, not a polling status. Report failed items and actual coverage before drawing conclusions about an entire channel.
Standalone comments collections
Start budgeted comments collections in the website. MCP can fetch individual comments/reply pages but has no tool to create this standalone job. Existing collections appear in list_jobs and get_job with kind: "comments",comments_pages, comments_count, and a stopping message on the detail response. Completed can mean the budget was reached.
Download those collections from History as JSON and CSV in a ZIP. list_job_videos can show their per-video status, including skipped rows when unfiltered, but its include_comments flag reads transcript-job samples only. There is no MCP cancellation or file-export tool; use the website, or the authenticated REST cancel/export endpoints.
Per-client install guides
Each guide walks the exact UI clicks, copy-paste config, and a “try it” prompt to verify the connection.
- Claude: covers Claude.ai web, Claude Desktop, Claude Code CLI, and the VS Code / JetBrains / Cursor extensions.
- ChatGPT: covers ChatGPT.com with Developer Mode and the OpenAI Responses API for developers.
- Grok: covers grok.com/connectors and the xAI API. Availability depends on whether your Grok account exposes the Connectors menu.
Costs and rate limits
Same plan, same credits as the web app. A transcript fetched through MCP charges the same single credit as a transcript fetched through the website. The per-plan rate limit from /api/v1 also covers /mcp, counted per account, so multiple chat clients on the same account share one budget.
Free tier users get 30 shared credits every 30 days, usable for transcripts or comments inside MCP. Search, listings, and video details remain free at any balance. Install the connector, try it, see if it’s worth upgrading.
Errors
Tool calls that fail return a structured MCP tool error to the chat client. The most common cases:
- Insufficient credits: not enough credits for this fetch. On a paid plan the balance resets at your next billing date. On the free plan the 30 credits reset every 30 days, counted from the day you signed up.
- Wrong URL type: passing a channel URL to
get_transcriptreturns an error directing you tolist_channel_videosfirst. - No captions: the video has no caption track. This generally needs a caption track to be added or processed before retrying helps. No credit charged.
- Transcript unavailable: temporarily could not be retrieved. Try again in a few minutes. No credit charged.