A YouTube MCP server for AI agents
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.
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
- One endpoint.
https://vidwords.com/mcpis a hosted Model Context Protocol server. Point ChatGPT, Claude, Cursor, VS Code or Codex at it and the assistant gains 22 tools for reading YouTube videos and monitoring channels — no integration code, no scraping, no proxy pool. - You sign in; you do not paste a key. Every major client finds the sign-in page on its own and shows a consent screen. Start from a setup link: Add to Claude · Add to Cursor · Add to VS Code. Claude asks you to review the prefilled connector before adding it. It spends the same Cloud and AI balances as the REST API, under the same plan limits, and Free accounts can connect too.
- The flagship tool is
search_transcript, notget_transcript. Both cost the same. Search returns only the moments that answer the question, each with a clickable timestamp; a full transcript of a two-hour video mostly fills the context window with material nobody asked about. - It reads the picture, not only the captions.
analyze_videolooks at slides, charts and demos, andask_videodrops any citation it cannot match to a recorded frame or a real transcript segment.
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.
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:
- Verify your email first. Until you click the verification link, every call returns
403with{"error":"email_unverified"}. This is the single most common first-call failure on a new account. - It is
Basic, notBearer. The token is used as-is; you do not base64-encode auser:passpair yourself.
The 22 tools
| Tool | What it does | Cost |
|---|---|---|
search_transcript | Find 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_transcript | Transcript 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_transcript | One 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_library | Search every transcript the account has already saved, with timestamps and deep links. | Free |
list_library | The account's saved videos, newest first. | Free |
list_languages | A video's caption tracks, and which are auto-generated (the speech) versus uploaded (possibly translations). | Free |
list_channel_videos | Resolve a channel handle, URL or UC… id to its recent uploads. | 1 Cloud Request · Starter and up |
list_watchlists | The account's Radar watchlists and how much each has recorded. | Free |
watchlist_activity | Newest uploads Radar has recorded for one watchlist. | Free |
create_watchlist | Create a named Radar watchlist. Automatic analysis starts off. | Free |
add_watchlist_channel | Monitor a channel URL, @handle or UC… id on a watchlist, up to 25 channels each. | Free |
check_watchlist | Check a watchlist's channels for new uploads now. Never starts a paid analysis. | Free |
update_watchlist | Rename 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_filters | Test unsaved title phrases against the latest 20 recorded uploads without saving anything. | Free |
remove_watchlist_channel | Stop monitoring one channel and delete its recorded history on that watchlist. | Free |
delete_watchlist | Delete a watchlist with its channels and recorded videos. | Free |
set_radar_paused | Pause or resume all Radar monitoring and digest emails for the account. | Free |
account | Plan and remaining Cloud and AI balances, so the agent can price a job before running it. | Free |
analyze_video | Start 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_analyses | The account's AI Watch analyses, newest first, with each analysisId, video, mode and status. Filters by video. | Free |
get_analysis | Read a finished analysis: chapters, key points, timestamped evidence. waitSeconds (up to 25) holds the call until it is ready instead of polling. | Free |
ask_video | Ask 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:
- ChatGPT — Plugins → Add custom MCP server; sign in and approve.
- Claude and claude.ai — open the prefilled setup link, confirm, then choose Register automatically.
- Claude Code — one
claude mcp addcommand. - Cursor — one click, or a block in
.cursor/mcp.json. - Codex CLI —
codex mcp add, thencodex mcp login.
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.
- Nothing to copy. No token, no config file, no restart.
- You approve it explicitly. Registration alone grants nothing — a connector has no access to any account until a signed-in person clicks Approve.
- You can take it back. Live connections are listed on your API page with a Disconnect button, and access stops immediately.
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
- The server is stateless by design. There are no resumable SSE streams and no session to delete; every tool answers in one shot.
GETandDELETEreturn a JSON-RPC error rather than an HTML 404, so a client that probes them gets something its own layer can read. list_channel_videosneeds the Starter plan or higher and uses one Cloud Request. Account and saved Radar/library reads are free.- RapidAPI tokens are refused here. That identity is metered per call on RapidAPI's side and has no account behind it, neither of which survives a tool-calling session. Use a VidWords API token.
- No captions, or the wrong ones. For a video with no caption track, pass
transcribeAudio: trueto transcribe it from the audio. When every caption track is an uploaded translation rather than the speech — the result saysselectionReason: "caption_fallback"— passsource: "audio"to read what is actually said. Both are paid, priced per minute of video, and never run unless asked for.