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

Most clients need no token at all. The server speaks OAuth, so the client registers itself, sends you to VidWords to sign in, and stores a credential it refreshes on its own. You can create the account during that sign-in step. The free plan includes monthly credits and 10 Watch minutes, so you can wire this up and use it before paying anything.

claude.ai, ChatGPT and Claude Desktop — add a connector, nothing to paste

Add this as a custom connector:

https://vidwords.com/mcp

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.

Claude Code

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

Then type /mcp in a session and choose Authenticate.

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "vidwords": {
      "url": "https://vidwords.com/mcp"
    }
  }
}

Cursor shows the server as Needs login — click that once and it runs the OAuth flow in your browser. Because this file carries no secret, it is safe to commit, which the header form below is not.

A static token instead

For CI, a container, or a client with no OAuth support, authenticate with a header. Create an account at vidwords.com/register, verify your email, then copy the token from your profile.

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" }
    }
  }
}

Keep this out of version control, or use ~/.cursor/mcp.json instead — the header holds a live credential.

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.

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/.

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.

Ask for a span, not a whole video

Both transcript tools take optional from and to timecodes — seconds (615), m:ss (10:20) or h:mm:ss (1:02:13):

{ "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.

One call across a channel

search_transcript accepts a list, which is how you answer "what has this channel said about X" without a round trip per video. Get the ids from list_channel_videos first:

{ "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_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

Read the full README on GitHub →