VidWords YouTube

A hostedModel Context Protocolserver that lets an AI agent read YouTube videos — and cite the exact second it got the answer from.

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

Get a free token: create an account atvidwords.com/register,verify your email, then copy the token from your profile. The free plan includes monthly credits and 10 Watch minutes, so you can wire this up and use it before paying anything.

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

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

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

[mcp_servers.vidwords] url = "https://vidwords.com/mcp" env_http_headers = { "Authorization" = "VIDWORDS_MCP_AUTH" }

export VIDWORDS_MCP_AUTH="Basic YOUR_API_TOKEN"

Donotusebearer_token_env_var. It is the obvious-looking field, but it sendsAuthorization: Bearer <value>and this server authenticates withBasic.

claude.ai and ChatGPT — OAuth, nothing to paste

Clients without custom-header support, and Docker

This repository also ships a smallstdio proxy(src/index.js) that speaks MCP on stdin/stdout and forwards tool calls to the hosted endpoint. Use it when your client cannot send a custom HTTP header, or when you want the server in a container:

{ "mcpServers": { "vidwords": { "command": "npx", "args": ["-y", "github:haljishi/vidwords-mcp"], "env": { "VIDWORDS_API_TOKEN": "YOUR_API_TOKEN" } } } }

Run straight from this repository — the proxy is not published to npm, so a barenpx @vidwords/mcpwill not resolve.

docker build -t vidwords-mcp . docker run --rm -i -e VIDWORDS_API_TOKEN=YOUR_API_TOKEN vidwords-mcp

The tool schemas are declared inline in the proxy, soinitializeandtools/listanswer without any credentials and the upstream is not contacted until a tool is actually called. A call withoutVIDWORDS_API_TOKENreturns a readable error rather than failing the handshake.VIDWORDS_MCP_URLoverrides the endpoint if you are pointing at a non-production instance.

The genericmcp-remotebridge works too:

{ "mcpServers": { "vidwords": { "command": "npx", "args": ["-y", "mcp-remote", "https://vidwords.com/mcp", "--header", "Authorization:Basic YOUR_API_TOKEN"] } } }

Ready-made config files live inexamples/.

{ "videos": ["dQw4w9WgXcQ"], "from": "10:20", "to": "11:00" }

These are the same formats the tools print back, so a timestamp out of one answer can be pasted straight into the next question. A timecode that cannot be parsed is refused before anything is fetched, so a typo costs no credit — it never silently widens to the whole video.

search_transcriptaccepts a list, which is how you answer "what has this channel said about X" without a round trip per video. Get the ids fromlist_channel_videosfirst:

{ "video": ["VIDEO_ID_1", "VIDEO_ID_2", "VIDEO_ID_3"], "query": "pricing" }

Each video is billed at the usual 1 credit, and one unavailable video is reported in its own row rather than failing the call — the others were fetched and charged for, so you still get them.

It reads the picture, not only the captions

analyze_videolooks at slides, charts, code samples and on-screen text that is never spoken aloud.ask_videothen answers against that stored analysis, andevery citation is checked before you see it: a visual claim has to match a frame that was actually recorded, a spoken claim has to land on a real transcript segment. Anything that fails is dropped, and when nothing survives the answer says the evidence is insufficient rather than producing a confident guess.

That is occasionally annoying — a refusal is a worse demo than a fluent answer — and it is the only version of this feature that is safe to put in front of an agent, because an agent repeats what it is told without the scepticism a human reader applies.

- Basic, notBearer.The token is sent as-is; you do not base64-encode auser:passpair.
- Verify your email first.Until you click the verification link every call returns403with{"error":"email_unverified"}— the most common first-call failure on a new account.
- Credits are one poolshared with the REST API and the website. One credit is one transcript. Frame analysis draws Watch minutes instead, and a run refused before it starts costs nothing.
- Rate limit: 30 requests / 10s— deliberately looser than the REST API's 5, because the server is stateless and a client re-runsinitializebefore every call.analyze_videohas its own ceiling of 10 starts per minute, shared with the REST route.
- RapidAPI tokens are refused here.That identity is metered per call and has no account behind it, neither of which survives a tool-calling session. Use a VidWords API token.
- Stateless by design.No resumable SSE streams, no session to delete; every tool answers in one shot.GETandDELETEreturn a JSON-RPC error rather than an HTML 404.
- Captions have to exist.For a video with no caption track, a signed-in account can transcribe from audio instead — priced by length, quoted before you spend.

skills/youtube-transcripts/SKILL.mdis a drop-in agent skill for this server — tool selection, timecode spans, channel-wide search, the cost table and the error codes worth acting on, in the format Claude and compatible agents load directly.

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

- Agent skill (SKILL.md)
- YouTube MCP server — overview
- Setup in Claude Code
- Setup in Claude Desktop
- Setup in Cursor
- REST API documentation

Open an issue here for anything about the MCP surface — a tool that misbehaves, a client whose config we have not documented, a schema that could be clearer. Account and billing questions go tosupport.

The contents of this repository (documentation and configuration examples) are MIT licensed. The hosted service itself is proprietary and governed by theVidWords terms.

Finds background music for YouTube shorts by analyzing script content and recommending tracks from YouTube Music.