← All guides

Give Claude Code YouTube video access

Written by the VidWords Team · August 18, 2026 · Updated August 18, 2026 · Report a correction

One command connects Claude Code to nine tools for searching transcripts, reading video frames, and citing exact timestamps.

The short answer

One command, no token to fetch first:

claude mcp add --transport http vidwords https://vidwords.com/mcp

Then type /mcp inside a session and choose Authenticate. Claude Code opens a browser, you sign in to VidWords once, and it stores a credential it refreshes by itself. claude mcp list confirms it registered; /mcp shows whether it actually connected. Claude Code now has nine tools for reading YouTube videos.

A static token instead

If you would rather pin a token — for CI, or a machine that cannot open a browser — pass it as a header and skip the sign-in step:

claude mcp add --transport http vidwords https://vidwords.com/mcp \
  --header "Authorization: Basic YOUR_API_TOKEN"

Get a token first

Only the static-token route above needs this; the /mcp sign-in issues its own credential. Create a free account and copy the API token from your profile. Two things to know before the first call:

• Verify your email. Until you click the verification link every call returns 403 with {"error":"email_unverified"} — the most common first-call failure on a new account.
• The scheme is Basic, not Bearer, and the token goes in as-is. You are not base64-encoding a user:pass pair.

Choosing a scope — and the mistake to avoid

claude mcp add writes the server into a config whose location depends on the scope you pick. The default is local to the current project. --scope user makes it available in every project you open, which is usually what you want for a service like this.

Be careful with project scope. A project-scoped server is written to a .mcp.json file inside the repository, and that file is meant to be committed so teammates inherit the same tooling. Your API token is in the header. Committing it publishes a working credential to everyone with repository access, and to anyone at all if the repo is public.

Use user scope for personal credentials. If you genuinely want the whole team on this server, commit the config without the token and have each person add their own, or keep the file out of version control.

What you can ask for

The point of wiring this into a coding assistant is that a great deal of engineering knowledge only exists on video — conference talks, migration walkthroughs, framework release streams — and none of it is greppable. Once the server is connected, requests like these work:

• "Search this conference talk for what they said about breaking changes, and give me the timestamps." → search_transcript, and you get clickable links back rather than a summary you have to trust.
• "Pull the transcripts for these eight videos and tell me which ones actually cover authentication." → get_transcript across a batch, up to 25 per call.
• "This tutorial shows the config on screen but never reads it out — what's in it?" → analyze_video then ask_video, which read the frames rather than the captions.

That last one is the case ordinary transcript tooling cannot serve at all. Screen-recorded tutorials put the important material — the config file, the terminal output, the diagram — on screen and say "as you can see here". A captions-only tool returns "as you can see here".

The nine tools

Prefer search_transcript over get_transcript. They cost the same, but dropping a full two-hour transcript into the context of a coding session evicts the code you were actually working on.

If it does not connect

• /mcp shows the server as failed. Almost always the header. Check for Basic rather than Bearer, and that the quotes survived your shell.
• Every tool call returns 403. Unverified email — click the link in the signup mail and retry.
• 429 during a burst. The limit is 30 requests per 10 seconds. A stateless server re-handshakes on every call, so one question can spend three requests; a wide fan-out over many videos hits this before you expect it.
• The tools never get called. Ask for the video by URL explicitly. Given a bare topic, the model will often answer from memory rather than reaching for a tool.

Get a free API token →