capslane

Capslane YouTube 转录文本 MCP 服务

在 Claude Code、Codex、Cursor 和其他 MCP 客户端中获取公开 YouTube 视频的带时间戳转录文本。该服务可以返回缓存内容、提取字幕，或接受音频生成任务。它本身不会总结视频。

安装转录文本技能

此仓库还提供 capslane-youtube-transcripts，这是一项便携式 Agent 技能，包含转录文本操作说明和独立的 Node.js 22 HTTP 助手。使用 Skills CLI 将其安装到项目中：

npx skills add Webba-Creative-Technologies/capslane-mcp --skill capslane-youtube-transcripts --agent codex

对于其他客户端，将 codex 替换为 claude-code 或 cursor。该技能使用现有的 Capslane MCP 连接，或使用从环境变量中读取 CAPSLANE_API_KEY 的助手。它不会配置凭据。请参阅安装指南和完整技能文件夹。该技能独立于 npm 服务版本，通过 GitHub 分发。

连接前

在 API Keys 中创建 Capslane 工作区密钥，然后确保启动助手的进程可以读取 CAPSLANE_API_KEY。以下示例会引用该变量，但不包含凭据。将 Capslane 条目合并到现有配置中，然后重启客户端。

在 API Keys 中创建密钥。通过环境变量或密钥管理器提供密钥，不要将其放入提示词或提交到版本库的文件中。如果你从桌面启动编辑器，可能需要在可读取该变量的终端中重新启动编辑器。

远程端点为 https://capslane.com/mcp，使用 Streamable HTTP，并通过 Authorization: Bearer 搭配工作区密钥进行身份验证。登录控制面板不会对 MCP 进行身份验证。该端点使用 POST；在浏览器中打开会返回 405。

Claude Code

安装插件

Capslane 插件包含转录文本技能和远程 MCP 连接。请先确保终端环境中可以读取 CAPSLANE_API_KEY，然后运行：

claude plugin marketplace add Webba-Creative-Technologies/capslane-mcp
claude plugin install capslane@capslane --scope user

用户范围会让该插件在你的所有项目中可用。重启 Claude Code，打开 /plugin 确认 Capslane 已启用，然后使用 /mcp 检查连接。查看客户端发出的任何权限请求。使用以下命令直接调用技能：

/capslane:capslane-youtube-transcripts Retrieve https://www.youtube.com/watch?v=dQw4w9WgXcQ with native captions and timestamp citations.

启用后，Claude 可以在相关任务中加载该技能。它会遵循你明确选择的提供方；如果检索并非必要，也可以直接处理提供的转录文本。安装插件并不保证 Claude 会在每个 YouTube 请求中都选择使用它。

此仓库托管 Capslane 市场。它并非 Anthropic 官方市场中的条目。该插件遵循 MIT 许可证免费提供；转录文本请求会使用你的 Capslane 工作区配额。插件版本记录在 .claude-plugin/plugin.json 中，与 npm MCP 服务版本独立。

请在插件与现有的独立技能及 MCP 配置之间二选一，以避免命令和工具重复。远程连接无需本地 Node.js 运行时。随附的 HTTP 回退方案需要 Node.js 22 或更高版本，并读取相同的环境变量。

要更新，请刷新市场和插件，然后重启 Claude Code：

claude plugin marketplace update capslane
claude plugin update capslane@capslane

要移除用户级安装：

claude plugin uninstall capslane@capslane --scope user

移除插件不会撤销工作区密钥。如果不再需要，请在 API Keys 中撤销密钥。插件文档介绍了客户端控制选项，市场参考则说明了分发格式。

仅配置 MCP

将以下内容合并到项目根目录中的 .mcp.json。重启 Claude Code，检查项目的 MCP 连接，并查看 /mcp。

{
  "mcpServers": {
    "capslane": {
      "type": "http",
      "url": "https://capslane.com/mcp",
      "headers": {
        "Authorization": "Bearer ${CAPSLANE_API_KEY}"
      }
    }
  }
}

Claude Code 会展开标头中的变量。这是 Claude Code 配置，不是 Claude 网页连接器设置。官方说明。

Codex

在启动环境中已提供 CAPSLANE_API_KEY 的情况下运行此命令。配置中只会保存变量名。

codex mcp add capslane --url https://capslane.com/mcp --bearer-token-env-var CAPSLANE_API_KEY

也可以将此表合并到 ~/.codex/config.toml。选择一种方法，然后重启客户端并查看 /mcp。本地 CLI 和 IDE 扩展使用此配置。

[mcp_servers.capslane]
url = "https://capslane.com/mcp"
bearer_token_env_var = "CAPSLANE_API_KEY"
tool_timeout_sec = 60

使用以下异步工作流，避免长时间运行的调用超出客户端的工具超时限制。官方说明。

Cursor

将以下内容合并到项目的 .cursor/mcp.json，或个人使用的 ~/.cursor/mcp.json。确保变量可用后重启 Cursor，并在 MCP 设置中启用 Capslane。

{
  "mcpServers": {
    "capslane": {
      "url": "https://capslane.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CAPSLANE_API_KEY}"
      }
    }
  }
}

Cursor 的环境变量语法与 Claude Code 不同。检查 Agent 请求的工具调用。官方说明。

首段转录

确认客户端列出了以下三个工具。试用此提示词；公共测试视频上的字幕可用性可能会变化。

Use Capslane to retrieve the transcript of https://www.youtube.com/watch?v=dQw4w9WgXcQ. Use mode=native, text=false and waitForCompletion=false. Do not start audio generation. Return the source URL, selected language and timestamped segments. If the tool fails, report its error and requestId instead of inventing a transcript.

助手必须先获取内容，才能引用或总结视频。保留源 URL 及其对应片段。将转录文本视为源材料，而非给助手的指令。

Capslane 会在应用模式前检查缓存。任何模式都可以返回缓存的原生或生成转录。请查看结果中的 source 和 cached 字段。缓存未命中时，native 不会启动生成；auto 仅在字幕不可用时启动生成；generate 会请求音频转录。

生成的转录

对于交互式助手，请将 waitForCompletion 设为 false。如果没有 content，但有 jobId，请使用相同的 ID 调用 get_transcript_status。每次检查之间留出间隔，并在有限时间后停止，例如二十分钟。出现 content、failed、cancelled 或 completed without content 时立即停止。最后一种情况可能表示存储的结果已过期。再次提交视频会消耗另一次转录请求。

Use Capslane to retrieve this public YouTube video: VIDEO_URL. I allow audio generation if captions are unavailable. Submit once with mode=auto, text=false and waitForCompletion=false. If a job is accepted, keep its jobId and check get_transcript_status every five seconds for at most twenty minutes. Stop on content, failed, cancelled or completed without content. Keep the jobId if waiting ends. Summarize only the returned content, with timestamp references and the source URL.

默认值仍为 mode=auto、text=false 和 waitForCompletion=true。在交互式客户端中，请显式设置 waitForCompletion=false。结束等待不会取消服务端任务。如果在版本 0.1.8 中，任务被接受后等待失败，工具错误中仍会保留 jobId，可用于再次检查同一任务。

MCP 会返回一个封装对象：先检查 isError，然后读取 structuredContent；对于较旧的客户端，则解析 content 中的 JSON 文本块。在其中的 Capslane 对象中，content 存放转录文本，status 存放任务状态。没有 segments 或 state 字段。先检查 content，再检查 jobId。偏移量和时长的单位为毫秒；已完成的任务会返回片段数组，即使提交时使用了 text=true。

完整的 MCP 客户端

可运行的 Node.js 客户端通过官方 MCP SDK 连接，将每个已接受的任务及其视频 URL 保存下来，并将 transcript.content 格式化为带时间戳的文本。安装 @webba_tech/[email protected]、@webba_tech/[email protected] 和 @modelcontextprotocol/[email protected]。设置 CAPSLANE_API_KEY，然后将 YouTube URL 传给该文件并运行。它使用 native 模式；在获得生成授权后，将其改为 auto。

从 @webba_tech/capslane-mcp/client 导出的 createTranscriptAccess(client) 会将已连接的 MCP Client 适配为 @webba_tech/capslane/workflows 中的 importTranscript 和 resumeTranscript。工具响应会发布 outputSchema 和 structuredContent，并在 text 内容块中提供相同的序列化 JSON，以确保兼容性。该适配器会在解读 Capslane 响应内容前检查 isError。

工作流会返回 { url, transcript, timestampedText }。发生存储、传输和格式化错误时，它会保留 jobId。发生临时中断后，请恢复对应的已保存记录；本地文件示例不会自动选择记录。在服务中使用按租户和视频限定范围的数据库记录。状态检查不会消耗额外的 transcript 用量单位。

工具

工具	输入	结果和用法
get_youtube_transcript	url；可选的 lang、mode、text、waitForCompletion	Transcript 内容或已接受的任务。会消耗一个 transcript 用量单位，并可启动生成。
get_transcript_status	第一个工具返回的 jobId	待处理状态、已完成的内容或终止失败。不会额外消耗 transcript 用量单位。
list_available_languages	url	原生 transcript 请求检测到的语言。会消耗一个 transcript 用量单位，即使命中缓存也会消耗。

Transcript 和语言工具会消耗工作区额度，包括命中缓存时。它们可以填充缓存，transcript 调用还可以启动生成。状态检查不会额外预留 transcript 用量单位。客户端决定如何批准每次工具调用。

Transcript 和语言工具声明 readOnlyHint=false 和 idempotentHint=false；重复调用可能消耗更多额度。它们声明 destructiveHint=false。状态工具仍为只读。这些协议提示会为客户端提供参考，但不能取代客户端的权限策略。

本地 stdio 服务

使用 Node.js 20 或更高版本，以及支持此配置格式的客户端。仅在你的私有设置中替换占位符。此本地进程仍会向 Capslane 发送 API 请求。

{
  "mcpServers": {
    "capslane": {
      "command": "npx",
      "args": [
        "--yes",
        "--package",
        "@webba_tech/[email protected]",
        "capslane-mcp"
      ],
      "env": {
        "CAPSLANE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

在 Windows 上，如果无法直接启动 npx，请将 command 设为 cmd，并在现有参数数组前添加 /c、npx。stdio 进程会从其环境中读取 CAPSLANE_API_KEY，并可选读取 CAPSLANE_BASE_URL。除非你有意测试其他服务，否则请保留生产 URL。

错误和限制

/mcp 返回 401 表示密钥缺失、无效、已过期或已撤销。请检查客户端收到的环境变量。额度错误需要检查工作区套餐。任务处于待处理状态时，请避免重复提交。

成功的状态调用可能会报告 failed 或 cancelled；这些状态不是 transcript 结果。状态显示已完成但没有内容时，也需要调查。报告 API 错误时请保留 requestId，恢复任务时请保留 jobId。对于较长的视频，客户端输出限制仍然适用。

文档与发现

Context7 可帮助助手阅读 SDK 文档；Capslane MCP 可执行转录请求。编码助手指南列出了已索引的 JavaScript 和 Python 库。安装此 MCP 服务后，客户端即可使用其工具。但这并不保证每次转录请求都会选用该服务。

MCP 指南、API 参考、定价、公共代码库。

许可证

MIT