tvsub MCP

tvsub MCP

tvsub-mcp 是 tvsub 的 MCP 配套工具。tvsub 是 macOS 上 Apple TV.app 的实验性字幕叠加工具。它允许 MCP 客户端查看当前播放项目、选择或翻译字幕文件、调整字幕外观、启动或停止叠加字幕，以及校准字幕时间。

支持的播放器：macOS Apple TV.app 中购买和租借的影片 （目前正在探索 Prime Video 支持，但尚不可用）。 字幕格式：SRT、SMI/SAMI、VTT。翻译可使用以下三种后端之一：Anthropic API 密钥、已登录的 Claude Code CLI（Claude 订阅），或已登录的 Codex CLI（ChatGPT 订阅）——订阅后端不会产生额外的 API 费用。

此服务不会下载字幕、绕过 DRM、修改视频或启动 TV.app。请提供你有权使用的字幕文件，并自行开始播放。

两种方向，同一套工作流

如果你在 Apple TV.app 中购买的外国、经典或多语言影片不包含韩语或其他所需语言的字幕，可以载入合法获取的字幕文件，使用 Claude 或 ChatGPT 订阅进行翻译，然后以叠加字幕的形式显示。同样的工作流也适用于相反方向：全球各地的观众都可以将合法获取的韩国电影和剧集字幕翻译成自己的语言。

如果你在 Apple TV.app 中购买的外国、经典或多语言影片没有韩语或你所需语言的字幕，可以载入合法持有的字幕文件，使用 Claude 或 ChatGPT 订阅进行翻译，然后以叠加字幕的形式显示。同样的方式也适用于全球各地的观众：将合法持有的韩国电影和剧集字幕翻译成自己的语言后观看。

要求

• macOS
• 已安装并构建的 tvsub
• Python 3.12 或更高版本
• 推荐使用 uv 进行 uvx 安装
• 翻译字幕需要以下之一：Anthropic API 密钥、已登录的 Claude Code CLI（Claude 订阅），或已登录的 Codex CLI （ChatGPT 订阅）。使用其他任何工具都不需要密钥或 CLI

安装并注册到 Claude Code

将 /absolute/path/to/tvsub 替换为包含 tvsub 的 build/、 config/、src/ 和 subtitles/ 目录的路径。

brew install uv

claude mcp add --transport stdio --scope user tvsub -- \
  uvx tvsub-mcp==0.3.0 \
  --tvsub-root /absolute/path/to/tvsub

claude mcp get tvsub
claude mcp list

翻译会自动选择后端：如果存在 Anthropic API 密钥，则优先使用；其次使用已登录的 Claude Code CLI；最后使用已登录的 Codex CLI。设置 TVSUB_TRANSLATE_BACKEND（auto、api、claude、codex）或 backend 工具参数即可覆盖此设置。登录了订阅 CLI 后，可以完全跳过密钥。若要使用 API 后端，请导出密钥并在注册服务时包含该密钥；也可以将密钥一次性存入 macOS Keychain（服务 kim.youngji.tvsub.anthropic），该服务也会读取其中的密钥。

export ANTHROPIC_API_KEY="your-key"

claude mcp add --transport stdio --scope user \
  --env ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  tvsub -- uvx tvsub-mcp==0.3.0 \
  --tvsub-root /absolute/path/to/tvsub

其他 stdio MCP 客户端也可以启动相同的命令：

uvx tvsub-mcp==0.3.0 --tvsub-root /absolute/path/to/tvsub

工具

工具	用途
now_playing	读取当前 Apple TV.app 的标题、内容 ID、播放位置和播放状态。
list_subtitles	列出并解析 tvsub 字幕库中的 SRT、SMI、SAMI 和 VTT 文件。
load_subtitle	为当前内容选择字幕文件，默认保留同步锚点。
translate_subtitle	估算或执行大模型翻译，并验证字幕条目和时间码。支持选择后端、注入术语表，以及按行或时间范围进行部分重译。
set_glossary	创建或更新每个标题对应的术语表（名称、尊称、关系、禁止使用的译法），并将其注入翻译提示词。
mark_reviewed	将已翻译字幕的来源标记从 ai_draft 更新为 user_reviewed。
list_fonts	列出已安装的 macOS 字体并检查示例字形覆盖情况。
set_style	更改字体、字号、颜色、描边、背景和屏幕位置。
start_overlay	使用所选字幕和样式启动 tvsub。
stop_overlay	仅停止由此服务启动的叠加层进程。
calibrate_sync	存储一个或多个对话锚点，并计算时间偏移和漂移。
status	汇总播放、叠加层、字幕、样式和校准状态。

翻译前，请调用 translate_subtitle 并设置 dry_run=true，以查看字幕条目数、批次数和预估费用。订阅后端显示 $0 (included in subscription)。每次翻译都会生成一个 .provenance.json 附属文件，记录后端、哈希值和审核状态。

使用统计

从 0.2.3 版本开始，匿名使用统计默认启用。 服务会在 ~/Library/Application Support/tvsub/telemetry.json 中存储随机安装 ID（UUIDv4）、每日工具调用数和翻译后端调用数，以及发送日期。首次启用运行时会向 stderr 打印通知；status 工具会报告是否启用了统计收集、发送了哪些数据，以及如何禁用。

启动时以及工具调用后，服务会检查今天之前尚未发送的数据。 它会通过后台 POST 请求发送最早的待发送日期，目标地址为 https://youngji.kim/api/tvsub/telemetry，每天最多发送一次。超时时间为 3 秒。失败的尝试会保留计数，并在下一个符合条件的日期重试；不会中断工具运行。TVSUB_TELEMETRY_URL 可覆盖收集器 URL。

JSON 仅包含 install_id、day、tvsub_mcp_version、macos_version （major.minor）、python_minor（major.minor）、tools（12 个工具名称的调用数） 以及 backends（api、claude、codex、pro 或 auto 的调用数）。未指定或为空的后端会计为 auto；这里记录的是请求的后端，而不是最终由翻译选择的后端。统计数据绝不包含字幕文本、标题、内容 ID、文件名、路径、术语表、API 密钥、原始错误或 IP 地址。

若要同时禁用记录和发送，请设置 TVSUB_TELEMETRY=0 （也可使用 false、off 和 no，不区分大小写），或在 MCP 服务的环境中设置 DO_NOT_TRACK=1。例如，在 claude mcp add 命令中、tvsub 之前添加 --env TVSUB_TELEMETRY=0。模拟模式（--mock 或 TVSUB_MCP_MOCK=1）和测试始终会禁用统计。禁用后，现有本地计数器会保留；禁用期间不会记录或发送任何统计数据。

重要声明

• 实验性软件： 请做好遇到问题和不兼容变更的准备。请备份 tvsub 配置和字幕文件。
• 发送至 Anthropic 的数据： 翻译会将选中的字幕文本及其上下文发送至 Anthropic API。加载、样式设置、同步和叠加层控制不会将字幕文本发送至 Anthropic。
• 由用户付费的 API 用量： api 后端使用你的 Anthropic API 密钥，所有费用均由你承担；费用估算可能与最终账单不同。claude 和 codex 后端通过你已登录的订阅版 CLI 运行，不会产生 API 费用。
• 私有 API 风险： tvsub 通过未公开的 macOS MediaRemote 接口读取 Apple 播放状态。Apple 不支持此集成，macOS 更新可能会更改或禁用它。
• 内容权利： 你有责任确保拥有处理和翻译字幕文件的权利。未经许可，请勿重新分发受版权保护的内容。
• 本项目独立于 Apple 和 Anthropic，与两者均无关联。

开发

python3.12 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m unittest discover -s tests -p 'test_*.py' -v
TVSUB_TEST_PYTHON="$PWD/.venv/bin/python" .venv/bin/python tests/stdio_smoke.py
bash scripts/hygiene-check.sh

发布版本前，请在仓库根目录运行 bash scripts/preflight.sh。

Linux 可以运行单元测试和模拟 stdio 冒烟测试。Apple TV.app、MediaRemote、CoreText 和实际叠加层需要 macOS。

许可证

MIT。请参阅 LICENSE。