← All guides

A YouTube MCP server for AI agents

Written by the VidWords Team · · Updated · Report a correction

Your assistant cannot watch a video. Point it at an MCP server and it can read one — and cite the exact moment it got the answer from.

An assistant calls VidWords get_analysis on a saved analysis of NASA's Perseverance landing, shows the VidWords result card with its chapters and key moments, highlights the heat-shield separation at 0:31, and answers with a link to that moment.
An example chat. The result card is the real one Claude and ChatGPT render, fed a saved get_analysis result, so reading it cost nothing.

What your assistant gets back

A selected excerpt from a real get_analysis result for NASA's Perseverance landing. The response carries the evidence and its source, so the answer can point back to the video.

{
  "start": 31,
  "end": 55,
  "title": "Heat Shield Separation",
  "description": "Circular camera view showing heat shield separation and first look at the Martian surface."
}

Read the full JSON response · See the analysis and source frame

Selected fields, not the complete response schema. AI output can be wrong; check the cited moment.

The short answer

Works with

Anything that speaks MCP over Streamable HTTP. Clients that can open a browser sign in with OAuth, so there is nothing to paste; anything headless — CI, a container — sends the API token as a header instead.

Claude Code
Setup guide
Claude Desktop
Setup guide
Cursor
Setup guide
Codex CLI
Setup guide
VS Code
One-click install
Windsurf
Custom header
Zed
Custom header
claude.ai
Setup guide
ChatGPT
Setup guide
Any MCP client
Header or OAuth

Logos are simplified marks for identification only; each product belongs to its own vendor and none of them endorse VidWords.

Why "a transcript" is the wrong unit to hand an agent

A language model cannot watch a video. That single limitation is why every "paste a YouTube link into ChatGPT" workflow disappoints — the model receives a URL, not the thing the URL points at.

The obvious fix is to give it the transcript. That works, and it is what most transcript APIs sell. But it quietly creates a second problem: a transcript is a wall of undifferentiated text with no addresses in it. An assistant handed 18,000 words can summarise them, but when you ask "where did they say that?" it has nothing to point at, so it either guesses a timestamp or hedges.

The useful unit for an agent is not a transcript. It is a grounded, linkable answer about a video — a claim with a timestamp attached that the person reading it can click and check in one second. That is what this server is built to return, and it is why search_transcript is the flagship tool rather than a convenience wrapper around get_transcript.

The endpoint

The whole configuration is a URL and a header:

POST https://vidwords.com/mcp
Authorization: Basic <your-api-token>

Get a token by creating a free account and creating a key on the API & MCP page. Two things trip people up on the first call:

The 22 tools

ToolWhat it doesCost
search_transcriptFind where a video discusses something. Takes one video or a list of up to 25, so one call can search a whole channel. Returns the matching moments with timestamps, quoted context, and youtube.com/watch?v=…&t=…s deep links.1 Cloud Request per new video
get_transcriptTranscript text for up to 25 videos, or the span between two timecodes. maxChars pages a long one, lang picks a caption track, source: "audio" transcribes the speech itself.1 Cloud Request per new video
translate_transcriptOne video’s transcript translated into any language by AI, line for line, every timestamp kept — for a language the video has no captions in, or an audio transcription. estimateOnly quotes the price first; reading it again is free.2 AI Units per started minute of video, only when it succeeds
search_librarySearch every transcript the account has already saved, with timestamps and deep links.Free
list_libraryThe account's saved videos, newest first.Free
list_languagesA video's caption tracks, and which are auto-generated (the speech) versus uploaded (possibly translations).Free
list_channel_videosResolve a channel handle, URL or UC… id to its recent uploads.1 Cloud Request · Starter and up
list_watchlistsThe account's Radar watchlists and how much each has recorded.Free
watchlist_activityNewest uploads Radar has recorded for one watchlist.Free
create_watchlistCreate a named Radar watchlist. Automatic analysis starts off.Free
add_watchlist_channelMonitor a channel URL, @handle or UC… id on a watchlist, up to 25 channels each.Free
check_watchlistCheck a watchlist's channels for new uploads now. Never starts a paid analysis.Free
update_watchlistRename or pause a watchlist, set digest emails, title include/exclude phrases and monthly analysis ceilings. Turning on automatic analysis spends AI Units at the usual Watch rates, so an agent should only do it when you ask.Free to change; analysis is billed
preview_watchlist_filtersTest unsaved title phrases against the latest 20 recorded uploads without saving anything.Free
remove_watchlist_channelStop monitoring one channel and delete its recorded history on that watchlist.Free
delete_watchlistDelete a watchlist with its channels and recorded videos.Free
set_radar_pausedPause or resume all Radar monitoring and digest emails for the account.Free
accountPlan and remaining Cloud and AI balances, so the agent can price a job before running it.Free
analyze_videoStart a frame-level analysis — slides, charts, demos and on-screen text, not just captions. Returns an analysisId immediately; estimateOnly: true quotes the price instead, without starting anything. A video with no captions is analyzed from its soundtrack unless transcribeAudio: true asks for a word-for-word transcript too.1 Cloud Request, then AI Units per minute: Standard analysis 4, Deep 30, Quick 2.8; estimate free
list_analysesThe account's AI Watch analyses, newest first, with each analysisId, video, mode and status. Filters by video.Free
get_analysisRead a finished analysis: chapters, key points, timestamped evidence. waitSeconds (up to 25) holds the call until it is ready instead of polling.Free
ask_videoAsk a question against a finished analysis. Citations are verified against stored evidence or dropped.6 AI Units per question

Re-reading a video the account already has is free — another time range, another page, or a search after a fetch — and every metered result reports what it charged.

The one habit worth forming: prefer search_transcript

Both transcript tools cost one Cloud Request per new video, so there is no billing reason to choose. The reason is context. Ask an assistant "what did this two-hour interview say about pricing?" and get_transcript returns roughly 20,000 words, of which perhaps 300 are about pricing. Those 300 words now compete for attention with 19,700 words that are not, and the answer gets worse, slower and more expensive to generate.

search_transcript returns the matching stretches with the surrounding context and a deep link per match. The assistant answers from the relevant material and hands you a timestamp you can click. Reach for get_transcript when you genuinely want the whole text — an export, a diff, a corpus — not when you have a question.

What it reads that a transcript API does not

Everything above operates on captions, which is where most YouTube tooling stops. Three of the tools do something different: they read the video's frames.

analyze_video starts a frame-level analysis — slides, charts, code samples, product demos, on-screen text that is never spoken aloud. Analysis takes minutes, so the tool returns an analysisId at once and get_analysis polls it. Starting the same analysis again on the same account — same video, mode and range — returns the existing one instead of charging twice; if it is still running, get_analysis with waitSeconds waits for it.

ask_video then answers questions against that stored analysis, and this is the part worth understanding before you trust it. Every citation is checked before you see it: a visual claim has to match a frame that was actually recorded, and a spoken claim has to land on a real transcript segment. Anything that fails the check is dropped. When nothing survives, the answer says the evidence is insufficient instead of producing a confident guess.

That behaviour is deliberate and it is occasionally annoying — a refusal is a worse demo than a fluent answer. It is also the only version of this feature that is safe to put in front of an agent, because an agent will repeat whatever it is told without the scepticism a human reader applies. If you want to see the output before wiring anything up, the demo page is one real, unedited analysis of Apple's 76-minute WWDC 2026 keynote, published exactly as the tool produced it.

What it costs

MCP and REST use the same entitlements: one delivered transcript uses one Cloud Request; Standard Watch uses 4 AI Processing Units per minute of video and Deep Watch 30. Every new account includes 100 Developer Requests, so you can wire the server up before paying.

account exists so an agent can check the balance and tell you what a batch will cost before it starts, rather than failing halfway through a 200-video job. It is free to call; a well-behaved agent calls it first. Full numbers are on the pricing page.

Rate limits

Per minute, by plan: 60 requests on Free, 200 on Starter, 500 on Pro and 1,000 on Team. Count requests, not questions, because an MCP request is not an MCP operation: the server is stateless, so a client re-runs initialize before every call, and a single agent turn routinely spends three or more requests (initialize → tools/list → tools/call) to do one unit of work. A wide fan-out across many videos reaches the limit sooner than the number of questions suggests.

analyze_video carries its own tighter ceiling of 10 starts per minute, shared with the REST route so you cannot double your budget by alternating transports.

A drop-in agent skill

Configuring the server tells an assistant the tools exist. It does not tell it which one to reach for, and the default instinct — pull the whole transcript, then read it — is the expensive one. So the tool-selection guidance is published as a skill file you can drop straight into your agent:

skills/youtube-transcripts/SKILL.md on GitHub.

git clone --depth 1 https://github.com/haljishi/vidwords-mcp
cp -r vidwords-mcp/skills/youtube-transcripts ~/.claude/skills/

It carries the things a model gets wrong unprompted: prefer search_transcript over get_transcript, pass from/to timecodes when the user names a span instead of fetching two hours and filtering, send a list of video ids to cover a channel in one call, and treat an "insufficient evidence" answer from ask_video as correct rather than something to retry. The cost table and the error codes worth acting on are in there too, so an agent can budget before it spends.

Set it up in your client

Five walkthroughs, each with the exact steps and how to confirm the tools actually loaded:

VS Code needs no guide: Add to VS Code installs it, and VS Code asks you to sign in the first time a tool runs. If the link does nothing, VS Code is not installed here — put {"servers":{"vidwords":{"type":"http","url":"https://vidwords.com/mcp"}}} in .vscode/mcp.json instead.

Any other MCP-compatible client works too — through sign-in if it supports MCP OAuth, otherwise with Authorization: Basic <your-api-token> as a header. The full tool reference lives in the API documentation.

Connecting from claude.ai or ChatGPT

In the web apps, sign in rather than pasting a token. This server runs an authorization server of its own: add https://vidwords.com/mcp as a custom connector (in Claude, choose Register automatically for the OAuth client) and the host registers itself, sends you here to sign in, and shows a consent screen naming exactly what it is asking for. A pasted token would work where a connector accepts a fixed header, but it does not refresh itself and stops working the day the key is rotated.

Access tokens last an hour and refresh silently; refresh tokens rotate on every use, so a stolen one stops working as soon as the real client refreshes.

Honest limits

Get a free API token →