VidWords YouTube

VidWords YouTube MCP 服务

一个托管的 模型上下文协议服务，让 AI Agent 读取 YouTube 视频，并引用答案对应的准确秒数。

大模型无法观看视频。将它指向此端点，它就能使用 14 种工具搜索转录文本、搜索你已保存的视频、读取视频的画面——幻灯片、图表、演示、屏幕文字——并回答问题，且引用内容会在你看到之前经过验证。

无需编写集成代码。无需抓取数据。无需代理池。

https://vidwords.com/mcp

这个 URL 就是全部配置。客户端通过 OAuth 登录，无需寻找或粘贴密钥；无头客户端则可以发送 Authorization: Basic <your-api-token>。

仅支持远程托管，无需安装或自行托管。此仓库是该端点的公开清单、配置参考和问题跟踪器。

---

快速开始

大多数客户端完全不需要令牌。 服务使用 OAuth，因此客户端会自行注册，将你带到 VidWords 登录，并保存可自动刷新的凭据。你可以在登录过程中创建账户。免费套餐每月包含 25 次 Cloud Requests 和 200 个 AI Units，因此你可以先接入并使用，无需付费。

Claude（claude.ai 和 Claude Desktop）

1. 选择 Customize → Connectors，然后选择 + Add → Add custom connector。
2. URL：https://vidwords.com/mcp
3. 在 OAuth 客户端选项中选择 Register automatically。VidWords 会自行注册每个连接器（动态客户端注册），因此 Claude 默认的“published identity”选项无法连接。
4. 连接后，登录 VidWords 并批准。

使用 Team 或 Enterprise 套餐时，所有者需先在 Organization settings → Connectors → Add → Custom → Web 中添加；之后，成员再从 Customize → Connectors 进行连接。

ChatGPT

1. 在 chatgpt.com 上打开 Plugins，选择 +，然后选择 Add custom MCP server。
2. 名称：VidWords · 服务 URL：https://vidwords.com/mcp · 身份验证：OAuth。
3. 接受风险警告并选择 Create as a plugin，然后登录 VidWords 并批准。
4. Install 新插件，然后在聊天中输入 @ 并选择 VidWords。

请在网页端完成此操作；如果使用工作区账户，可能需要管理员允许自定义 MCP 服务。

无论哪种方式，宿主都会自行注册，将你带到 VidWords 登录，并显示明确列出其所请求权限的授权页面。仅注册不会授予任何权限——只有已登录用户点击 Approve 后才会开始访问；你可以通过 API & MCP 页面立即撤销活动连接。

使用配置文件设置 Claude Desktop

claude_desktop_config.json 只运行**本地（stdio）**服务——不支持在其中配置远程 url 条目（而且有报告称这会清空文件的 mcpServers 部分）。如果仍要在文件中声明该服务，可以使用 mcp-remote 桥接，它会在浏览器中运行相同的登录流程——仍然无需粘贴任何内容：

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

编辑文件后，退出并重新打开 Claude Desktop。

Claude Code

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

然后在会话中输入 /mcp 并选择Authenticate。

Cursor — 一键添加，或使用 .cursor/mcp.json

使用上方的 Add to Cursor 按钮，或：

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

Cursor 会将该服务显示为需要登录——点击一次，它就会在浏览器中运行 OAuth 流程。由于此文件不包含密钥，因此可以安全提交；下方的标头表单则不能。

VS Code

使用上方的 Add to VS Code 按钮，或将以下内容放入 .vscode/mcp.json：

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

该服务首次启动时，VS Code 会提示你登录。

Codex CLI

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

改用静态令牌

对于 CI、容器或不支持 OAuth 的客户端，可以使用标头进行身份验证。在 vidwords.com/register 创建账户，验证电子邮件，然后在 API & MCP 页面创建密钥。密钥的值只会在创建时显示一次。

Claude Code

claude mcp add --transport http vidwords https://vidwords.com/mcp \
  --header "Authorization: Basic YOUR_API_TOKEN"

Claude Desktop — claude_desktop_config.json

使用与上文相同的 mcp-remote 桥接方式，但使用密钥而非登录信息。将密钥放在 env 中：Windows 上的 Claude Desktop（以及 Cursor 和 Codex CLI）不会转义 args 中的空格，因此写在其中的 Basic YOUR_API_TOKEN 会被拆成两部分——mcp-remote README 自带的解决方法是：

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

请勿将此文件纳入版本控制，或者改用 ~/.cursor/mcp.json——标头中包含有效凭据。

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"

请勿使用 bearer_token_env_var。它看起来显而易见，但会发送 Authorization: Bearer <value>，而此服务使用 Basic 进行身份验证。

不支持自定义标头的客户端，以及 Docker

此仓库还提供了一个小型 stdio 代理（src/index.js），它通过 stdin/stdout 使用 MCP，并将工具调用转发到托管端点。如果你的客户端无法发送自定义 HTTP 标头，或者你希望在容器中运行该服务，请使用它：

{
  "mcpServers": {
    "vidwords": {
      "command": "npx",
      "args": ["-y", "github:haljishi/vidwords-mcp"],
      "env": { "VIDWORDS_API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

可直接从此仓库运行——该代理未发布到 npm，因此裸用 npx @vidwords/mcp 将无法解析。

docker build -t vidwords-mcp .
docker run --rm -i -e VIDWORDS_API_TOKEN=YOUR_API_TOKEN vidwords-mcp

工具架构在代理中内联声明，因此 initialize 和 tools/list 无需任何凭据即可响应。资源发现也在本地完成；只有在请求工具、提示词或 UI 资源时才会联系上游。 该代理还提供分析和账户 MCP Apps 资源。兼容的宿主可以渲染交互式卡片；分析卡片包含显示完整分析。UI 资源读取和工具调用使用相同的已验证上游，结构化结果会原样传递。

未设置 VIDWORDS_API_TOKEN 时，调用会返回易于理解的错误，而不会导致握手失败。如果你要连接非生产环境，可以使用 VIDWORDS_MCP_URL 覆盖端点。

通用的 mcp-remote 桥接方式同样适用：

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

现成的配置文件位于 examples/。

---

这十四种工具

它们由两种额度支付：Cloud Request 用于获取一部视频的转录文本，AI Units 用于读取画面和转录音频——每次新的画面分析都会消耗两种额度： 转录文本消耗 1 个 Cloud Request，另加每分钟视频对应的 AI Units。账户已经获取过的视频会保存在 其 Library 中，再次读取免费——读取另一个时间范围、另一页内容，或获取后再搜索都免费。每项按量计费的结果都会报告其 charged。

工具	功能	费用
search_transcript	查找视频中讨论某个主题的位置。支持传入一部视频，或最多 25 部视频的列表，因此一次调用即可回答跨整个频道的问题。返回匹配片段的时间戳、引用上下文，以及 youtube.com/watch?v=…&t=…s 深层链接。可选参数：from/to。	每部新视频 1 个 Cloud Request
get_transcript	获取最多 25 部视频的转录文本，或两个时间码之间的片段。lang 用于选择字幕轨道，maxChars 用于分页读取较长的转录文本，source: "audio" 用于直接转录语音。	每部新视频 1 个 Cloud Request
translate_transcript	将视频转录文本通过 AI 翻译成任意语言，逐行翻译：每行都保留时间戳，因此阅读、引用和下载方式与原文相同。适用于视频没有所需语言字幕的情况（此时 get_transcript 会返回 language_unavailable，并提供 aiTranslation 选项），也可用于翻译音频转录文本。estimateOnly: true 只返回价格，不执行翻译。	每开始一分钟视频消耗 2 个 AI Units，仅在成功时扣费；重新打开免费 · 新视频另需 1 个 Cloud Request
search_library	对账户已保存的所有转录文本进行全文搜索，并返回时间戳和深层链接。	免费
list_library	按时间从新到旧列出账户保存的视频，以及最近完成的分析 ID。	免费
list_analyses	列出已保存的 AI Watch 分析，包括 ID、状态和结果链接；支持分页和按视频筛选。	免费
list_languages	列出视频的字幕轨道，并标明哪些是自动生成的（语音），哪些是上传的（可能是翻译字幕）。	免费
list_channel_videos	根据频道句柄、URL 或 UC… ID 获取该频道最近上传的视频。	1 个 Cloud Request · Starter 套餐及以上
list_watchlists	列出账户的 Radar 关注列表及各列表已记录的数量。	免费
watchlist_activity	列出某个关注列表中 Radar 已记录的最新上传视频。	免费
account	查看套餐和两种额度余额，让 Agent 在执行任务前估算费用。	免费
analyze_video	开始进行逐帧分析——分析幻灯片、图表、演示和屏幕文字，而不仅限于字幕。立即返回 analysisId。mode 可选 quick、smart、deep 或 auto；只要 AI Units 充足，任何套餐都可运行 Deep。estimateOnly: true 只返回价格，不会启动分析。	1 个 Cloud Request，另加每分钟视频对应的 AI Units：Quick 2.8，Standard 4，Deep 30 · 估算免费
get_analysis	读取已完成的分析：概览、章节、要点、带时间戳的证据和步骤。省略 analysisId 即可打开最近完成的结果。waitSeconds（最长 25 秒）会让调用等待结果就绪，而不是轮询。	免费
ask_video	针对已完成的分析提问。引用内容会与已存储的证据核实，不匹配的引用会被舍弃。	每个问题 6 个 AI Units

先检查 Library

search_library 和 list_library 可以免费读取账户已有的内容。Agent 如果在再次获取视频前先搜索 Library，就能回答“我上周看的那段采访是怎么谈定价的”，既不花费额度， 也无需往返请求。

优先使用 search_transcript，而非 get_transcript

处理每个新视频，两者都只需 1 次 Cloud Request，因此没有账单上的理由让你选择其中一个。原因在于上下文。 问“这场两小时的访谈谈到了什么定价内容？”时，get_transcript 会返回大约 20,000 个单词，其中可能只有 300 个与定价有关——这 300 个单词现在要与 其余 19,700 个不相关的单词争夺注意力，答案也会变得更差、更慢，生成成本更高。

search_transcript 只返回匹配的片段，每段都附有深层链接。只有在确实需要全文时才使用 get_transcript：例如导出、比较差异或建立语料库。

指定片段，而不是整个视频

两个转录工具都接受可选的 from 和 to 时间码——秒数（615）、m:ss （10:20）或 h:mm:ss（1:02:13）：

{ "videos": ["dQw4w9WgXcQ"], "from": "10:20", "to": "11:00" }

这些格式与工具返回的格式相同，因此可以直接将某个回答中的时间戳粘贴到下一个问题中。无法解析的时间码会在获取任何内容前被拒绝，因此拼写错误不会产生任何成本——它绝不会悄悄扩大到整个视频。

分页获取长转录，而不是猜测范围

get_transcript 接受 maxChars。被截断的结果会注明 truncated: true，并带有 用于继续读取的起始位置 nextFrom；将它作为 from 传回即可。截断位置始终在字幕之间，而且首次获取之后的每一页都是重新读取 Library 中已有的视频——免费。

{ "videos": ["dQw4w9WgXcQ"], "maxChars": 20000 }

获取的语言是什么，以及原因

字幕轨道的语言不一定是视频中的口语语言。自动生成的轨道会转录语音；上传的轨道则可能是翻译——有些视频带有十几种社区翻译，却没有任何一种字幕轨道使用实际口语。因此，每份转录都会说明选择该字幕轨道的原因：

• selectionReason：requested、spoken_language（与口语一致）、caption_fallback （没有已知字幕轨道与口语一致——如果有英语字幕，则会选择它以提高可读性）、 translated 或 audio_transcription。

• spokenLanguage：已知时为口语所用语言，否则为 null——不会猜测。

• lang 用于请求字幕轨道。如果视频没有该语言的轨道，get_transcript 会返回 language_unavailable，并列出实际提供的语言 availableLanguages，且不收费。

• source: "audio" 会转录实际说出的内容，而不是读取字幕——当所有字幕都是翻译时，这是获取原文的方式。其价格与任何音频转录相同（每分钟视频需 3 个 AI Units，另加 Cloud Request），传入此参数即表示同意。

• 如果没有你需要的语言字幕轨道，而且 YouTube 也无法翻译成该语言？translate_transcript 会使用 AI 将转录翻译成任意语言，同时保留时间戳（每开始一分钟需 2 个 AI Units，仅在成功时收费一次；再次读取免费）。

list_languages 会根据已存储的内容免费回答同样的问题。

一次调用搜索整个频道

search_transcript 接受列表，因此你可以回答“这个频道谈过什么 X”，而无需每个视频都单独往返调用一次。先通过 list_channel_videos 获取视频 ID：

{ "video": ["VIDEO_ID_1", "VIDEO_ID_2", "VIDEO_ID_3"], "query": "pricing" }

每个新视频按通常的标准收取 1 次 Cloud Request；不可用的视频会单独列在结果的一行中，不会导致整个调用失败——其他视频已经获取并收费，所以你仍然可以得到它们。

它读取的是画面，而不只是字幕

analyze_video 会查看幻灯片、图表、代码示例和从未被说出口的屏幕文字。随后，ask_video 会根据已存储的分析作答，每条引文都会在你看到之前经过核验：视觉内容的说法必须与实际记录的画面相符，语音内容的说法必须对应真实的转录片段。任何未通过核验的内容都会被剔除；如果没有内容通过，答案就会说明证据不足，而不是给出自信的猜测。

这有时会让人恼火——拒绝作答不如流畅回答那样适合演示——但这是唯一能安全地交给 Agent 使用的版本，因为 Agent 会照单全收，不像人类读者那样会保持怀疑。

---

身份验证、费用和限制

• 如果你粘贴了令牌：用 Basic，而不是 Bearer。 令牌会原样发送；无需将 user:pass 对进行 Base64 编码。已登录的客户端会携带自己的凭据，因此不受此限制。
• 请先验证邮箱。 在你点击验证链接之前，每次调用都会返回 403 和 {"error":"email_unverified"}——这是新账户首次调用失败最常见的原因。
• 余额与 REST API 和网站共享。 一次 Cloud Request 对应一份新转录；画面分析会消耗 1 次 Cloud Request 和 AI Units，音频转录则会在 Cloud Request 之外额外消耗 AI Units。运行在开始前被拒绝时不收费，analyze_video 设置 estimateOnly: true 时可免费报价。
• 每分钟速率限制按套餐而定： Free 为 60 次，Starter 为 200 次，Pro 为 500 次，Team 为 1,000 次请求。服务端无状态，因此客户端每次调用前都会重新运行 initialize，一次工具调用会产生多个请求。analyze_video 有自己的上限：每分钟启动 10 次，与 REST 路由共享。
• 这里不接受 RapidAPI 令牌。 这种身份按调用计费，且没有关联账户，这两点都不适用于工具调用会话。请使用 VidWords API 令牌。
• 采用无状态设计。 不支持可恢复的 SSE 流，也没有可删除的会话；每个工具都会一次性返回结果。GET 和 DELETE 会返回 JSON-RPC 错误，而不是 HTML 404。
• 没有字幕，或字幕不对。 如果视频没有字幕轨道，请传入 transcribeAudio: true，根据音频进行转录；如果要替换已有字幕（例如所有上传的翻译），请传入 source: "audio"。这两项都是付费功能，按视频分钟数计费，且只会在明确请求时运行。

完整价格：pricing。

---

提示词

该服务还提供三个提示词，Claude 等客户端会将其显示为可直接使用的操作。每个提示词都会告诉模型要使用哪些工具，以及按什么顺序使用，并优先选择成本最低的方式。

提示词	参数	功能
summarize_video	video	以可用的最低成本方式阅读单个视频，并生成带时间戳的摘要。
research_channel	channel、topic	查找某个频道关于某个主题的内容，并附上引用片段。
find_in_my_library	topic	搜索所有已保存的内容——免费。

Agent 技能

skills/youtube-transcripts/SKILL.md 是适用于此服务的即插即用 Agent 技能——它涵盖工具选择、时间码范围、频道级搜索、费用表以及值得采取行动的错误代码，并采用 Claude 和兼容 Agent 可直接加载的格式。

将该文件夹复制到 Agent 的技能目录中：

git clone --depth 1 https://github.com/haljishi/vidwords-mcp
cp -r vidwords-mcp/skills/youtube-transcripts ~/.claude/skills/

此技能假设 MCP 服务已配置（请参阅 Quick start）。它的作用是让读过该技能的助手知道，应使用带时间码范围的 search_transcript，而不是将一整段两小时的转录内容都载入上下文。

文档

• Agent 技能（SKILL.md）
• YouTube MCP 服务 — 概览
• 在 Claude Code 中设置
• 在 Claude Desktop 中设置
• 在 Cursor 中设置
• 在 ChatGPT 中设置
• 在 Codex CLI 中设置
• REST API 文档

支持

如果遇到与 MCP 接口相关的问题，请在此处提交 issue，例如工具运行异常、我们尚未记录其配置的客户端，或可以写得更清晰的架构。账户和账单问题请联系 支持团队。

许可证

本仓库的内容（文档和配置示例）采用 MIT 许可证。托管服务本身为专有服务，受 VidWords 条款约束。

---

独立产品；与 YouTube 或 Google 无关。