YouTube Transcript Index

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 for Codex, Claude Code, WorkBuddy/CodeBuddy, Windows paths, and optional settings.

Run the standalone workspace

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

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

Claude Code

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:

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

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:

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

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

---

中文说明

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

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

开发运行：

npm install
npm run studio

生成可分享的 Agent 插件：

npm run package:plugin

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