vidwords-mcp

# 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.**

[![MCP Registry](https://img.shields.io/badge/MCP_Registry-com.vidwords%2Fyoutube-blue)](https://registry.modelcontextprotocol.io)
[![Docs](https://img.shields.io/badge/docs-vidwords.com-4f46e5)](https://vidwords.com/resources/youtube-mcp-server?utm_source=github&utm_medium=readme&utm_campaign=mcp)

[![Add to Cursor](https://img.shields.io/badge/Add_to-Cursor-000000?style=for-the-badge)](https://cursor.com/en/install-mcp?name=vidwords&config=eyJ1cmwiOiJodHRwczovL3ZpZHdvcmRzLmNvbS9tY3AifQ%3D%3D)
[![Add to VS Code](https://img.shields.io/badge/Add_to-VS_Code-0098FF?style=for-the-badge)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522vidwords%2522%252C%2522type%2522%253A%2522http%2522%252C%2522url%2522%253A%2522https%253A%252F%252Fvidwords.com%252Fmcp%2522%257D)

A language model cannot watch a video. Point it at this endpoint and it gains thirteen 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 <your-api-token>` 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](https://vidwords.com/api-keys?utm_source=github&utm_medium=readme&utm_campaign=mcp)
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`](https://www.npmjs.com/package/mcp-remote),
which runs the same sign-in flow in your browser — still nothing to paste:

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

Quit and reopen Claude Desktop after editing the file.

### Claude Code

```bash
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:

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

### VS Code

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

```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

```bash
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](https://vidwords.com/api-keys?utm_source=github&utm_medium=readme&utm_campaign=mcp).
A key's value is shown once, when it is created.

### Claude Code

```bash
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:

```json
{
  "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`

```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`

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

```bash
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:

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

```bash
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`](https://www.npmjs.com/package/mcp-remote) bridge works too:

```json
{
  "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/`](./examples).

---

## The thirteen 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`.

| Tool | What it does | Cost |
| --- | --- | --- |
| `search_transcript` | Find where a video discusses something. Takes one video **or a list of up to 25**, so one call can answer a question across a whole channel. Returns the matching moments with timestamps, quoted context, and `youtube.com/watch?v=…&t=…s` deep links. Optional `from`/`to`. | 1 Cloud Request per new video |
| `get_transcript` | Transcript text for up to 25 videos, or the span between two timecodes. `lang` picks a caption track, `maxChars` pages a long transcript, `source: "audio"` transcribes the speech