← All guides

Give Cursor YouTube video access

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

A block in .cursor/mcp.json gives Cursor nine tools for reading YouTube videos — plus one credential mistake worth avoiding first.

The short answer

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "vidwords": {
      "url": "https://vidwords.com/mcp",
      "headers": { "Authorization": "Basic YOUR_API_TOKEN" }
    }
  }
}

Cursor picks it up without a restart in most cases; the MCP section of Settings shows whether the server connected and which tools it exposes. Use ~/.cursor/mcp.json instead to make it available in every project.

Get a token first

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.

Do not commit the project file

This is the one thing worth getting right before anything else. .cursor/mcp.json sits inside the repository and gets committed by default — and the header holds a live API token. Committing it hands a working credential to everyone with repository access, and to the entire internet if the repo is public.

Either put the server in ~/.cursor/mcp.json, which is outside the repo and covers every project anyway, or add .cursor/mcp.json to .gitignore before your first commit. If a token has already been pushed, rotate it — deleting the file does not remove it from history.

Using it in Agent mode

MCP tools are available to Cursor's agent, which means the model decides when to call them. Two habits make that reliable:

• Give it the URL. "Summarise the React Conf keynote" invites an answer from memory; pasting the link makes the tool the obvious route.
• Ask for timestamps. It steers the model toward search_transcript rather than get_transcript, and you get citations you can click instead of a summary you have to take on faith.

The workflow this unlocks in an editor is narrow but genuinely underserved: a great deal of framework knowledge is published as conference talks and screen recordings and never written down. Being able to ask "what did they say the migration path was, with timestamps" without leaving the editor removes a context switch that otherwise costs half an hour.

Reading what is on the screen

Screen-recorded tutorials are the case where captions fail completely. The presenter says "as you can see here" and the actual content — the config, the terminal output, the diagram — exists only in the picture. analyze_video reads frames as well as speech, and ask_video answers against that analysis with every citation checked against a recorded frame; anything that cannot be matched is dropped rather than guessed at.

The nine tools

If it does not connect

• Server shows as failed in Settings. Check the header is Basic, not Bearer, and that the JSON parses.
• 403 on every call. Unverified email — click the link from signup.
• Tools listed but never used. Agent mode has to be active, and the request needs to make a video the obvious subject. Paste the URL.
• 429 during a wide search. 30 requests per 10 seconds, and a stateless server re-handshakes on every call, so a fan-out across many videos reaches it quickly.

Get a free API token →