← All guides

A YouTube MCP server for AI agents

Written by the VidWords Team · August 18, 2026 · Updated August 18, 2026 · 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.

The short answer

• One endpoint. POST https://vidwords.com/mcp is a hosted Model Context Protocol server. Point Claude, Claude Code or Cursor at it and the assistant gains nine tools for reading YouTube videos — no integration code, no scraping, no proxy pool.
• One header for auth. Authorization: Basic <your-api-token> — the same token as the REST API, spending the same Cloud and AI balances under the same plan limits. Free accounts get one too.
• The flagship tool is search_transcript, not get_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_video looks at slides, charts and demos, and ask_video drops any citation it cannot match to a recorded frame or a real transcript segment.

Works with

Anything that speaks MCP over Streamable HTTP. Desktop and CLI clients authenticate with a token header; claude.ai and ChatGPT sign in with OAuth instead, so there is nothing to paste.

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 copying it from your profile. Two things trip people up on the first call:

• Verify your email first. Until you click the verification link, every call returns 403 with {"error":"email_unverified"}. This is the single most common first-call failure on a new account.
• It is Basic, not Bearer. The token is used as-is; you do not base64-encode a user:pass pair yourself.

The nine tools

The one habit worth forming: prefer search_transcript

Both transcript tools cost one Cloud Request per 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 nine 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. A video that has been analysed before comes back ready immediately rather than being charged twice.

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 3 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

30 requests per 10 seconds — deliberately looser than the REST API's 5. The reason is that 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. At the REST budget a normal conversation would start returning 429s on its second question.

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

Three walkthroughs, each with the exact config and how to confirm the tools actually loaded:

• Claude Code — one claude mcp add command.
• Claude Desktop — a block in claude_desktop_config.json.
• Cursor — a block in .cursor/mcp.json.
• Codex CLI — a block in ~/.codex/config.toml, below.

Codex CLI

Codex configures MCP servers in ~/.codex/config.toml (or .codex/config.toml for a single trusted project). Give it the URL and the header:

# ~/.codex/config.toml
[mcp_servers.vidwords]
url = "https://vidwords.com/mcp"
env_http_headers = { "Authorization" = "VIDWORDS_MCP_AUTH" }

then export the value the variable names:

export VIDWORDS_MCP_AUTH="Basic YOUR_API_TOKEN"

Do not reach for bearer_token_env_var here. It is the obvious-looking field and it sends Authorization: Bearer <value>, but this server authenticates with Basic. env_http_headers is the escape hatch for exactly this case — a server whose scheme is not Bearer — and it keeps the token in the environment rather than in a file you might commit.

Any other MCP-compatible client works too, provided it can send a custom header. The full tool reference lives in the API documentation.

Connecting from claude.ai or ChatGPT

The web apps are the one place you do not paste a token. Their custom-connector UIs authenticate over OAuth and cannot send a custom header, so this server runs an authorization server of its own: add https://vidwords.com/mcp as a custom connector and the host registers itself, sends you here to sign in, and shows a consent screen naming exactly what it is asking for.

• 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. GET and DELETE return a JSON-RPC error rather than an HTML 404, so a client that probes them gets something its own layer can read.
• list_channel_videos needs 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.
• Captions have to exist. For a video with no caption track at all, a signed-in account can transcribe from audio instead — priced by length, quoted before you spend.

Get a free API token →