VidWords YouTube

VidWords YouTube MCP Server

A hosted [Model Context Protocol](https://modelcontextprotocol.io) 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 fourteen tools for searching transcripts, searching the videos you have already saved, 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.

https://vidwords.com/mcp

That URL is the whole configuration. Clients sign in over OAuth — no key to find or paste — and headless ones can send Authorization: Basic instead.

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 25 Cloud Requests and 200 AI Units a month, so you can wire this up and use it before paying anything.

Claude (claude.ai and Claude Desktop)

1. Customize → Connectors, then + Add → Add custom connector.
2. URL: https://vidwords.com/mcp
3. Under the OAuth client options choose Register automatically. VidWords registers each connector itself (dynamic client registration), so Claude's default "published identity" option will not connect.
4. Connect, sign in to VidWords, and approve.

On a Team or Enterprise plan an owner adds it first, under Organization settings → Connectors → Add → Custom → Web; members then connect from Customize → Connectors.

ChatGPT

1. On chatgpt.com, open [Plugins](https://chatgpt.com/plugins), select +, then Add custom MCP server.
2. Name: VidWords · Server URL: https://vidwords.com/mcp · Authentication: OAuth.
3. Accept the risk warning and select Create as a plugin, then sign in to VidWords and approve.
4. Install the new plugin, then type @ in a chat and pick VidWords.

Do this on the web; on a workspace account an admin may need to allow custom MCP servers.

Either way, 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 the API & MCP page with immediate effect.

Claude Desktop from a config file

claude_desktop_config.json only runs local (stdio) servers — a remote url entry there is not supported (and has been reported to wipe the file's mcpServers section). To declare the server in the file anyway, bridge it with mcp-remote, which runs the same sign-in flow in your browser — still nothing to paste:

{

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

Quit and reopen Claude Desktop after editing the file.

Claude Code

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

Then type /mcp in a session and choose Authenticate.

Cursor — one click, or .cursor/mcp.json

Use the Add to Cursor button above, or:

{

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

VS Code

Use the Add to VS Code button above, or put this in .vscode/mcp.json:

{

"servers": { "vidwords": { "type": "http", "url": "https://vidwords.com/mcp" } } }

VS Code asks you to sign in the first time the server starts.

Codex CLI

codex mcp add vidwords --url https://vidwords.com/mcp

codex mcp login vidwords

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](https://vidwords.com/register?utm_source=github&utm_medium=readme&utm_campaign=mcp), verify your email, then create a key on the API & MCP page. A key's value is shown once, when it is created.

Claude Code

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

--header "Authorization: Basic YOUR_API_TOKEN"

Claude Desktop — claude_desktop_config.json

The same mcp-remote bridge as above, with the key instead of the sign-in. Keep the key in env: Claude Desktop on Windows (and Cursor, and the Codex CLI) do not escape spaces inside args, so Basic YOUR_API_TOKEN written there splits in two — the mcp-remote README's own workaround:

{

"mcpServers": { "vidwords": { "command": "npx", "args": ["-y", "mcp-remote", "https://vidwords.com/mcp", "--header", "Authorization:${VIDWORDS_MCP_AUTH}"], "env": { "VIDWORDS_MCP_AUTH": "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 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. Resource discovery is also local; the upstream is contacted when a tool, prompt, or UI resource is requested. The proxy also exposes the analysis and account MCP Apps resources. Compatible hosts can render interactive cards; the analysis card includes Show full analysis. UI resource reads and tool calls use the same authenticated upstream, and structured results pass through unchanged.

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:${VIDWORDS_MCP_AUTH}"], "env": { "VIDWORDS_MCP_AUTH": "Basic YOUR_API_TOKEN" } } } }

Ready-made config files live in examples/.

---

The fourteen tools

Two balances pay for them: a Cloud Request fetches one video's transcript, and AI Units pay for reading frames and for transcribing audio — a fresh frame analysis spends one of each kind: 1 Cloud Request for its transcript, plus AI Units per minute of video. A video the account has already fetched is in its Library, and reading it again is free — another time range, another page, a search after a fetch. Every metered result reports what it charged.

| get_analysis | Read a finished analysis: overview, chapters, key points, timestamped