{
  "markdown": "# tvsub MCP\n\n<!-- mcp-name: io.github.launzi/tvsub-mcp -->\n\n[![M8ven Score](https://m8ven.ai/badge/mcp/launzi-tvsub-mcp-cp2qjl?variant=verified)](https://m8ven.ai/mcp/launzi-tvsub-mcp-cp2qjl)\n\n`tvsub-mcp` is the MCP companion for [tvsub](https://youngji.kim/tvsub), an\nexperimental subtitle overlay for Apple TV.app on macOS. It lets an MCP client\ninspect the current playback item, choose or translate a subtitle file, adjust\nits appearance, start or stop the overlay, and calibrate subtitle timing.\n\nSupported player: purchased and rented films in macOS Apple TV.app\n(Prime Video support is being explored and is not currently available).\nSubtitle formats: SRT, SMI/SAMI, VTT. Translation runs on your choice of\nthree backends: an Anthropic API key, a signed-in Claude Code CLI\n(Claude subscription), or a signed-in Codex CLI (ChatGPT subscription) —\nsubscription backends add no API charges.\n\nThe server does not download subtitles, bypass DRM, modify video, or launch\nTV.app. You provide subtitle files that you have the right to use and start\nplayback yourself.\n\n## Two directions, one workflow\n\nIf a foreign, classic, or multilingual film you purchased in Apple TV.app does not include Korean—or another language you need—bring a lawfully obtained subtitle file, translate it with your Claude or ChatGPT subscription, and display it as an overlay. The same workflow works in the other direction: viewers worldwide can translate lawfully obtained subtitles for Korean films and series into their own language.\n\nApple TV.app에서 구매한 외화·고전·다국어 영화에 한국어 또는 원하는 언어 자막이 없다면, 정당하게 보유한 자막 파일을 불러와 Claude나 ChatGPT 구독으로 번역한 뒤 오버레이로 표시할 수 있습니다. 같은 방식으로 전 세계 시청자도 한국 영화와 시리즈의 정당하게 보유한 자막을 자신의 언어로 번역해 시청할 수 있습니다.\n\n## Requirements\n\n- macOS\n- [tvsub](https://youngji.kim/tvsub), installed and built\n- Python 3.12 or later\n- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) for the\n  recommended `uvx` installation\n- For subtitle translation, one of: an Anthropic API key, a signed-in\n  Claude Code CLI (Claude subscription), or a signed-in Codex CLI\n  (ChatGPT subscription). No key or CLI is needed for any other tool\n\n## Install and register with Claude Code\n\nReplace `/absolute/path/to/tvsub` with the directory containing tvsub's\n`build/`, `config/`, `src/`, and `subtitles/` directories.\n\n```bash\nbrew install uv\n\nclaude mcp add --transport stdio --scope user tvsub -- \\\n  uvx tvsub-mcp==0.2.2 \\\n  --tvsub-root /absolute/path/to/tvsub\n\nclaude mcp get tvsub\nclaude mcp list\n```\n\nTranslation picks a backend automatically: an Anthropic API key if present,\nthen a signed-in Claude Code CLI, then a signed-in Codex CLI. Set\n`TVSUB_TRANSLATE_BACKEND` (`auto`, `api`, `claude`, `codex`) or the\n`backend` tool argument to override. With a subscription CLI signed in you\ncan skip the key entirely. To use the API backend, export your key and\ninclude it when registering the server — or store it once in macOS Keychain\n(service `kim.youngji.tvsub.anthropic`), which the server also reads.\n\n```bash\nexport ANTHROPIC_API_KEY=\"your-key\"\n\nclaude mcp add --transport stdio --scope user \\\n  --env ANTHROPIC_API_KEY=\"$ANTHROPIC_API_KEY\" \\\n  tvsub -- uvx tvsub-mcp==0.2.2 \\\n  --tvsub-root /absolute/path/to/tvsub\n```\n\nOther stdio MCP clients can launch the same command:\n\n```bash\nuvx tvsub-mcp==0.2.2 --tvsub-root /absolute/path/to/tvsub\n```\n\n## Tools\n\n| Tool | Purpose |\n| --- | --- |\n| `now_playing` | Read the current Apple TV.app title, content ID, position, and playback state. |\n| `list_subtitles` | List and parse SRT, SMI, SAMI, and VTT files in tvsub's subtitle library. |\n| `load_subtitle` | Select a subtitle file for the current content while preserving sync anchors by default. |\n| `translate_subtitle` | Estimate or perform an LLM translation with cue and timecode validation. Supports backend selection, glossary injection, and partial retranslation by line or time range. |\n| `set_glossary` | Create or update a per-title glossary (names, honorifics, relationships, forbidden translations) that is injected into translation prompts. |\n| `mark_reviewed` | Promote a translated subtitle's provenance from `ai_draft` to `user_reviewed`. |\n| `list_fonts` | List installed macOS fonts and check sample glyph coverage. |\n| `set_style` | Change font, size, colors, outline, background, and screen position. |\n| `start_overlay` | Start tvsub with the selected subtitle and style. |\n| `stop_overlay` | Stop only the overlay process started by this server. |\n| `calibrate_sync` | Store one or more dialogue anchors and calculate timing offset and drift. |\n| `status` | Summarize playback, overlay, subtitle, style, and calibration state. |\n\nBefore translating, call `translate_subtitle` with `dry_run=true` to review the\ncue count, batch count, and estimated cost. Subscription backends report\n`$0 (included in subscription)`. Every translation writes a `.provenance.json`\nsidecar recording backend, hashes, and review status.\n\n## Important notices\n\n- **Experimental software:** expect rough edges and breaking changes. Keep a\n  backup of your tvsub configuration and subtitle files.\n- **Data sent to Anthropic:** translation sends the selected subtitle text and\n  surrounding subtitle context to the Anthropic API. Loading, styling, sync,\n  and overlay controls do not send subtitle text to Anthropic.\n- **User-paid API usage:** the `api` backend uses your Anthropic API key and\n  all charges are your responsibility; estimates can differ from the final\n  bill. The `claude` and `codex` backends run through your own signed-in\n  subscription CLIs and add no API charges.\n- **Private API risk:** tvsub reads Apple playback state through undocumented\n  macOS MediaRemote interfaces. Apple does not support this integration and a\n  macOS update may change or disable it.\n- **Content rights:** you are responsible for having the right to process and\n  translate subtitle files. Do not redistribute protected content without\n  permission.\n- This project is independent from and not affiliated with Apple or Anthropic.\n\n## Development\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install -e .\n.venv/bin/python -m unittest discover -s tests -p 'test_*.py' -v\nTVSUB_TEST_PYTHON=\"$PWD/.venv/bin/python\" .venv/bin/python tests/stdio_smoke.py\nbash scripts/hygiene-check.sh\n```\n\nBefore tagging a release, run `bash scripts/preflight.sh` from the repository root.\n\nLinux can run the unit tests and mock stdio smoke test. Apple TV.app,\nMediaRemote, CoreText, and the real overlay require macOS.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 6535,
  "sha": "17500134c5d18648ea6d7fc35a7802b0e68ee63ea3b49520537bd34d89ed9107",
  "repo_slug": "launzi/tvsub-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_launzi_tvsub_mcp_3a022e85/readme"
}