通过 MCP 连接 AI 助手

连接 AI 助手

Set up CaptionBolt's local MCP server for me and connect my account. Do the steps you can perform instead of only explaining them, and reply in the language I use in this conversation.

Facts:
- Server name: captionbolt. It is a local STDIO MCP server started with the command npx and the arguments --yes @captionbolt/mcp@0.3.3
- It must run on the computer that has my videos and my browser; WSL on that computer counts. It needs Node.js 22.12 or later and an active CaptionBolt Max subscription.
- Sign-in command: npx --yes @captionbolt/mcp@0.3.3 login
  It prints an authorization URL and tries to open it in my browser, waits up to five minutes for me to approve access, then saves the authorization on this computer. Running it first also downloads the package. The URL returns to a local address, so it only works in a browser on this computer.
- On native Windows, a client that cannot start npx directly needs the command cmd with the arguments /c npx --yes @captionbolt/mcp@0.3.3
- Verify with the read-only get_account tool; remaining minutes = credits.availableCreditsSec / 60.
- Clients that cannot run local servers use the remote server https://api.captionbolt.com/mcp instead; it cannot upload files from my computer or save results there.

Steps:
1. Identify my AI client, operating system and shell, and adapt every command, configuration format and file path to them. Check the Node.js version. If you are not running on my computer (for example over SSH, in a container or in a cloud workspace), tell me the smallest step to run there.
2. Start the sign-in command in the background and read its output. As soon as it shows the authorization URL, send me a message that contains that exact URL as plain text, before you run any other command or read any file. Tell me to approve access in the browser window it opened, or to open the URL on this computer if none appeared. I cannot see command output, so never refer to "the link above". Then let the command keep running until it reports success; if you cannot keep a command running, ask me to run it in my own terminal. If it reports that CaptionBolt is already authorized, continue. If it reports that an eligible integration account is required, tell me a Max subscription is needed and stop.
3. Add the server to my client's personal MCP configuration and keep other servers; prefer the client's own command for adding MCP servers. Update a captionbolt entry that uses another @captionbolt/mcp version; ask before replacing one that points elsewhere. A typical entry, to adapt to my client: {"mcpServers": {"captionbolt": {"command": "npx", "args": ["--yes", "@captionbolt/mcp@0.3.3"]}}}
4. Reload the MCP tools as my client requires, then call get_account and report my remaining minutes. If I must restart the client or open a new conversation first, tell me exactly what to do and give me one sentence to send there, such as "Call CaptionBolt get_account and show my remaining minutes."
5. Tell me what succeeded and anything left for me. Once it works, tell me I can ask in my own words, for example "Add captions to <path to my video>".

Rules:
- Do not upload, create, export, retry or cancel anything during setup.
- Ask before installing or upgrading software such as Node.js.
- Do not invent a login URL or ask for my password, an API key or a copied token. If a sandbox blocks network access, the browser or the credential store, ask me for permission or ask me to run the command myself.
- A saved configuration or a finished sign-in is not proof; only a successful get_account call is.

Reference: https://captionbolt.com/integrations/mcp

手动安装

CaptionBolt 本地 MCP 服务器是 npm 包 @captionbolt/mcp，适用于能运行本地 STDIO MCP 服务器的 AI 客户端，例如 Codex、Claude Code、Claude Desktop、Cursor 和 VS Code。它需要 Node.js 22.12 或更高版本。集成能力向 Max 订阅用户开放。

先在存放视频的电脑上，从终端登录一次。这一步也会下载安装包：

npx --yes @captionbolt/mcp@0.3.3 login

1. 浏览器会打开 CaptionBolt。如果没有自动打开，请打开终端中显示的授权链接。
2. 登录需要操作项目的账户，按提示完成账户设置。
3. 检查申请的权限，选择 允许访问。
4. 等待终端提示账户验证成功。

然后在 AI 客户端的 MCP 配置中添加服务器。很多客户端使用以下格式：

{
  "mcpServers": {
    "captionbolt": {
      "command": "npx",
      "args": ["--yes", "@captionbolt/mcp@0.3.3"]
    }
  }
}

不同客户端的配置格式可能不同，使用相同的命令和参数即可。在原生 Windows 上，如果客户端无法直接启动 npx，请把命令设为 cmd，参数设为 /c npx --yes @captionbolt/mcp@0.3.3。

WSL 也算同一台电脑：在 WSL 里运行的 AI 客户端中安装服务器，Windows 中的文件用 /mnt/c/Users/<name>/Videos/interview.mp4 这样的路径表示。登录链接会在 Windows 浏览器中打开。

最后，重启 AI 客户端或开启新对话，让它加载 CaptionBolt 工具。

授权信息保存在系统凭据存储中，会自动续期。在没有钥匙串的 Linux 和 WSL 上，保存在只有你能读取的 ~/.config/captionbolt/mcp-credentials.json。无需 API Key 或手动复制令牌。要从这台电脑上移除授权，把同一命令中的 login 换成 logout 运行即可。

验证连接

向助手发送以下请求：

Show my remaining CaptionBolt processing minutes and recent projects.
Do not create, export, retry or cancel anything.

连接正常时，可以读取账户限制并列出可访问项目。尚无符合条件的视频项目时，列表为空是正常的。

为电脑上的视频加字幕

用你自己的话提出请求，并说明是哪个文件：

Add captions to ~/Videos/interview.mp4

助手会开始上传这个文件，并在上传期间问你使用哪种字幕样式。它会推荐几种样式，以及你在 CaptionBolt 中保存的预设。回复编号、描述想要的效果，或者让助手决定都可以。

处理完成后，加好字幕的视频会保存在原视频旁边，例如 interview.captioned.mp4。已有文件永远不会被覆盖，同名时会改用带编号的文件名。助手还会给出项目的编辑器链接：打开后可以修改文字或更换样式，再在 CaptionBolt 中重新导出。

SRT、VTT、ASS、TXT 等字幕文件会随视频一起导出，可以在同一个请求里或之后再让助手保存：

Add captions to ~/Videos/interview.mp4 and also save the SRT file.

如果想先在编辑器里检查字幕再导出，先说明需要检查。

本地服务器只读取你指定的文件，不会扫描文件夹；视频直接上传到 CaptionBolt 存储，不会进入 AI 对话。支持 MP4、MOV、WebM 和 AVI 文件。处理会使用账户的时长和限制，与在网站上传相同。

使用 CaptionBolt 工具

本地服务器提供以下工具：

| 任务 | 工具 | | --- | --- | | 从电脑上传视频 | upload_file, get_upload_progress | | 暂停、继续或取消上传 | pause_upload, resume_upload, get_upload, abort_upload | | 把完成的导出保存到电脑 | download_result, get_download_progress | | 查询处理时长和限制 | get_account | | 查找字幕样式和已保存预设 | list_styles, list_presets | | 列出项目和查看进度 | list_projects, get_project | | 等待处理完成 | wait_for_project | | 查询请求的操作是否成功 | get_operation | | 用已完成的上传创建项目 | create_project | | 导出已保存的修改 | export_project | | 重试或取消项目 | retry_project, cancel_project | | 获取已完成导出的下载链接 | get_result |

也可以处理在网站上创建的项目。例如：

List my CaptionBolt projects that are ready for review.
Show their IDs and file names. Do not export them yet.

在 CaptionBolt 中检查并保存项目后：

Export project <project-id> as MP4 using its saved changes.
Check the operation, then the project status, and save the video on my
computer when the project is completed. If either fails, show the error and stop.

用工具返回的 ID 替换 <project-id>。operation 达到 completed 表示操作成功，视频可能仍在处理或导出。检查项目，直到 ready 可供检查或 completed 可下载。失败时停止并查看错误；查询之间遵循 pollAfterSeconds，项目取消后停止轮询。

mode: "review" 会停在 ready，以便你在 CaptionBolt 中检查；mode: "auto-export" 会在处理后直接导出 MP4 和套餐允许的字幕文件，不经过这一步。创建和修改项目需要项目写入权限；导出和自动导出另需导出权限。

自动导出项目停在 ready 时，检查 get_project 返回的 autoExport.state 和 autoExport.error。自动操作失败则报告错误并停止，不要持续等待下载，也不要未经指示发起另一项导出。

导出前先在编辑器中保存。已完成项目保留现有导出；需要修改时，在 CaptionBolt 中创建可编辑副本。请求其中没有的格式会立即报错。下载链接最长有效十分钟，可在项目的 14 天访问期内重新获取。

不安装本地服务器的连接方式

如果 AI 客户端不能运行本地服务器（例如网页版助手），请使用远程 MCP。远程 MCP 提供相同的项目工具，但不能上传电脑上的文件，也不能把结果保存到电脑。客户端需要支持远程 MCP、Streamable HTTP 和浏览器 OAuth 登录。

Name: CaptionBolt
Server URL: https://api.captionbolt.com/mcp
Transport: Streamable HTTP
Authentication: OAuth

这些是连接信息，不是配置文件。不同客户端的字段名称和配置格式可能不同；有些将传输方式标为 HTTP。使用完整服务 URL，不添加末尾斜杠。

1. 在 AI 客户端的 MCP 设置或配置中添加服务。
2. 启动客户端的登录或授权操作，浏览器会打开 CaptionBolt。
3. 登录需要操作项目的账户，按提示完成账户设置。
4. 检查申请的权限，选择 允许访问。
5. 返回客户端，确认 CaptionBolt 工具可用。

客户端会处理 OAuth 连接；只支持 API Key 请求头的客户端不能连接此端点。使用远程 MCP 时，先在 CaptionBolt 网站上传视频，再通过 MCP 查询项目并导出已保存的修改。自动化流程必须先完成 REST 上传流程，再将上传 ID 作为 uploadSessionId 传给 create_project。

远程 MCP 不接受远程视频 URL，也不管理上传会话。两种服务器都不编辑字幕或视觉设置，请在编辑器中修改。通知通过 Webhooks 单独配置。

管理连接

在设置 → 集成中查看已授权的 MCP 连接，并断开指定连接。

断开后，该连接及已保存令牌不能继续请求。运行 logout 只会删除这台电脑上本地服务器的授权；要撤销授权，请在设置中断开。退出 CaptionBolt 网站不会断开 MCP。这些操作都不会取消已接受任务；需要停止时，明确执行项目取消操作。

排查问题

| 问题 | 检查事项 | | --- | --- | | 没有 CaptionBolt 工具 | 本地服务器：确认 Node.js 为 22.12 或更高版本、命令和参数正确，然后重启客户端。远程 MCP：确认支持 Streamable HTTP 和 OAuth，服务地址准确 | | 工具返回 AUTH_REQUIRED | 在终端中重新运行 login 命令，然后重试 | | 登录提示凭据存储不可用 | 解锁 macOS 钥匙串或 Windows 凭据管理器，或改用远程 MCP | | 浏览器没有打开 | 在同一台电脑上打开终端中显示的授权链接 | | 允许访问后浏览器无法连接 127.0.0.1 | 在运行 login 的同一台电脑上、命令仍在运行时打开链接；命令已结束则重新运行 login | | 客户端无法启动 npx 或 node | 桌面应用可能不使用终端的 PATH。填写 npx 的完整路径，或把 Node.js 所在目录加入该服务器的 PATH；原生 Windows 上使用命令 cmd 和参数 /c npx … | | 客户端要求 API Key | 使用本地服务器或客户端的 OAuth 登录；API Key 用于 REST，不用于 MCP | | 连接已断开或过期 | 本地服务器重新运行 login；远程 MCP 在客户端重新发起授权 | | 操作被拒绝 | 检查已授权权限及账户当前限制 | | 请求被限流 | 按服务返回的等待时间重试 | | 项目失败 | 先读取错误，再明确重试；参见 API 状态和错误 |

本地服务器会申请项目 scope projects:read、projects:write、exports:write，以及用于自动续期的 offline_access。远程客户端若允许指定 OAuth scope，使用相同的 scope；未申请 offline_access 时，访问过期后可能需要重新登录。

创建项目、导出、重试和取消需要工具参数 idempotencyKey，使用 1–128 个无空格的可打印 ASCII 字符。每次新操作使用新的随机值（例如 UUID）；超时后查询已知 operation，或用原键重发完全相同的工具调用，不要假定操作失败。确认项目失败后的显式 retry_project 是新操作，需使用新键。

程序处理工具错误时，读取 structuredContent.error 中的 message 和 kind，以及可用时返回的 status、code、requestId 和 retryAfterSeconds。遵循等待时间，不要反复调用失败的工具。