# YouTube Transcript Index

[![MIT License](https://img.shields.io/badge/license-MIT-161616.svg)](LICENSE)
[![Node 22+](https://img.shields.io/badge/node-22%2B-43853d.svg)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-stdio-7657ff.svg)](https://modelcontextprotocol.io/)

An open-source, local-first YouTube research workspace for Codex, Claude Code, WorkBuddy/CodeBuddy, and other agents that can run stdio MCP servers.

Paste a public YouTube URL and get a grounded summary, timestamped moments, topic chapters, reusable copy, and up to 10 highly liked public comments. Spreadsheet import handles batches. The transcript comes first; if captions aren't available, the tool stops instead of guessing from a title.

## What it does

- Reads existing public captions with timestamps.
- Produces a one-sentence takeaway, a compact summary, and distinct points.
- Links every selected moment and chapter back to the matching point in the video.
- Pulls up to 10 highly liked public top-level comments from YouTube's returned candidate set.
- Scans XLSX, XLS, XLSM, CSV, and TSV files for YouTube links, including Excel hyperlinks.
- Writes Chinese or English output and keeps the latest 100 results in browser storage.
- Runs as a visual localhost workspace and as a set of MCP tools.

Comments remain in their original wording. They represent audience reactions, not verified facts.

## Two ways to run it

### Install it in an Agent

The Agent plugin starts a private web workspace on `127.0.0.1` when its MCP process starts. Ask the Agent:

> Open the YouTube Transcript Index web UI.

The Agent calls `get_web_ui_status` and returns the active address. The default is `http://127.0.0.1:3000`; if that port is occupied, the server tries the next local port.

The plugin page tries these analysis adapters in order:

1. MCP Sampling, when the host implements it.
2. A locally signed-in Codex CLI.
3. A locally signed-in Claude Code CLI.

Set `YTI_ANALYSIS_PROVIDER` to `sampling`, `codex`, or `claude` when you need a fixed adapter.
Analysis has a 10-minute default deadline. Set `YTI_ANALYSIS_TIMEOUT_MS` to another value in milliseconds when the host needs a different limit. The web page provides a cancel button, and cancellation stops the active local Agent process.

See [AGENT-PLUGIN.md](AGENT-PLUGIN.md) for Codex, Claude Code, WorkBuddy/CodeBuddy, Windows paths, and optional settings.

### Run the standalone workspace

```bash
npm install
npm run studio
```

Open `http://localhost:3000`. This mode uses the Codex installation already signed in on the computer.

## Agent installation

Requirements:

- Node.js 22.13 or newer
- [uv](https://docs.astral.sh/uv/)
- An Agent with local stdio MCP support
- Internet access to YouTube

Unzip the plugin release to a stable folder, then register its bundled server.

### Codex

```bash
codex mcp add youtube-transcript-index -- node "/ABSOLUTE/PATH/scripts/mcp-server.bundle.mjs"
```

### Claude Code

```bash
claude mcp add --scope user youtube-transcript-index -- node "/ABSOLUTE/PATH/scripts/mcp-server.bundle.mjs"
```

### WorkBuddy / CodeBuddy

Add the server in the product's MCP settings or in the project's `.mcp.json`:

```json
{
  "mcpServers": {
    "youtube-transcript-index": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/scripts/mcp-server.bundle.mjs"]
    }
  }
}
```

Use forward slashes in Windows JSON paths, for example `C:/Tools/youtube-transcript-index/scripts/mcp-server.bundle.mjs`.

## MCP tools

| Tool | Purpose |
| --- | --- |
| `get_web_ui_status` | Returns the active localhost URL and selected analysis adapter. |
| `get_youtube_transcript` | Fetches timestamped captions with pagination for long transcripts. |
| `get_youtube_comments` | Returns up to 10 highly liked public comment excerpts. |
| `scan_youtube_workbook` | Finds and deduplicates YouTube links in a local spreadsheet. |

All four tools are non-destructive. Transcript and comment text are treated as untrusted source material, never as instructions to the Agent.

## Batch input

Upload an `.xlsx`, `.xls`, `.xlsm`, `.csv`, or `.tsv` file in the web workspace. The importer checks populated cells and Excel hyperlinks across every worksheet, merges duplicate video IDs, and queues up to 100 videos per batch. Each finished result goes into local browser history immediately.

The raw scanner accepts up to 500 distinct links. The web queue uses a lower limit so a mistaken upload doesn't start hundreds of model requests.

## Build the plugin package

```bash
npm run package:plugin
```

The archive and its SHA-256 file are written to `release/`. The packaged MCP server is a single JavaScript bundle, so recipients don't need this repository's `node_modules` folder.

Portable desktop archives can also be assembled on macOS:

```bash
npm run package:mac
npm run package:windows
```

These builds include Node.js and uv. The macOS archives aren't notarized unless the distributor signs and notarizes them separately; read `MAC-FIRST-START.txt` before sharing one.

## Development

```bash
npm test
npm run lint
npm run test:mcp
```

The test suite builds the web app, initializes the bundled MCP server, checks the localhost page, and verifies the rendered workspace. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

## Privacy and limits

- HTTP listeners bind only to `127.0.0.1`.
- Browser history stays in that browser's local storage.
- Captions and public comments go directly to YouTube.
- Analysis uses the recipient's own Agent login; no credentials are included in release files.
- Caption access can fail for private videos, disabled captions, regional restrictions, age gates, or temporary YouTube blocking.
- “Top comments” means the highest-liked items in YouTube's returned public candidate set, not a guaranteed ranking of every comment on the video.

This project isn't affiliated with YouTube, Google, OpenAI, Anthropic, or Tencent. YouTube is a trademark of Google LLC.

## License

MIT. See [LICENSE](LICENSE).

---

## 中文说明

YouTube Transcript Index 是一个本地运行的开源视频整理工具。粘贴 YouTube 公开视频链接后，它会根据字幕生成一句话结论、主要内容、可跳转高光、时间轴、分享文案和最多 10 条高赞公开评论。

安装 MCP 插件后，Agent 启动插件时会同步在 `127.0.0.1` 启动完整网页。在 Agent 中输入“打开 YouTube Transcript Index 网页”即可获取当前地址。

开发运行：

```bash
npm install
npm run studio
```

生成可分享的 Agent 插件：

```bash
npm run package:plugin
```

历史记录只保存在当前浏览器。项目不会根据标题猜测视频内容，也不会把任何人的 Agent 登录凭据放入发布包。