VidWords YouTube MCP Server

A hosted Model Context Protocol server that lets an AI agent read YouTube videos — and cite the exact second it got the answer from.

A language model cannot watch a video. Point it at this endpoint and it gains nine tools for searching transcripts, reading a video's frames — slides, charts, demos, on-screen text — and answering questions with citations that are verified before you see them.

No integration code. No scraping. No proxy pool.

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

Remote-only and hosted — there is nothing to install or self-host. This repository is the public manifest, configuration reference and issue tracker for that endpoint.

Quick start

Get a free token: create an account at vidwords.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 Code

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

Claude Desktop — claude_desktop_config.json

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

Cursor — .cursor/mcp.json

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

Codex CLI — ~/.codex/config.toml

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

export VIDWORDS_MCP_AUTH="Basic YOUR_API_TOKEN"

Do not use bearer_token_env_var. It is the obvious-looking field, but it sends Authorization: Bearer <value> and this server authenticates with Basic.

claude.ai and ChatGPT — OAuth, nothing to paste

Add https://vidwords.com/mcp as a custom connector. The host registers itself, sends you to VidWords to sign in, and shows a consent screen naming exactly what it is asking for. Registration alone grants nothing — access begins only when a signed-in person clicks Approve, and live connections can be revoked from your API page with immediate effect.

Clients without custom-header support, and Docker

This repository also ships a small stdio 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 bare npx @vidwords/mcp will 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, so initialize and tools/list answer without any credentials and the upstream is not contacted until a tool is actually called. A call without VIDWORDS_API_TOKEN returns a readable error rather than failing the handshake. VIDWORDS_MCP_URL overrides the endpoint if you are pointing at a non-production instance.

The generic mcp-remote bridge 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 in examples/.

Related MCP server: YouTube Transcript MCP Server

The nine tools

Prefer search_transcript over get_transcript

Both cost one credit per video, so there is no billing reason to choose. The reason is context. Ask "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 now compete for attention with 19,700 that are not, and the answer gets worse, slower and more expensive to generate.

search_transcript returns only the matching stretches, each with a deep link. Reach for get_transcript when you genuinely want the whole text: an export, a diff, a corpus.

It reads the picture, not only the captions

analyze_video looks at slides, charts, code samples and on-screen text that is never spoken aloud. ask_video then answers against that stored analysis, and every 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.

Auth, cost and limits

• Basic, not Bearer. The token is sent as-is; you do not base64-encode a user:pass pair.

• Verify your email first. Until you click the verification link every call returns 403 with {"error":"email_unverified"} — the most common first-call failure on a new account.

• Credits are one pool shared 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-runs initialize before every call. analyze_video has 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. GET and DELETE return 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.

Full numbers: pricing.

Documentation

• YouTube MCP server — overview

• Setup in Claude Code

• Setup in Claude Desktop

• Setup in Cursor

• REST API documentation

Support

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 to support.

License

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

Independent product; not affiliated with YouTube or Google.