tvsub MCP server

tvsub MCP

<!-- mcp-name: io.github.launzi/tvsub-mcp -->

tvsub-mcp is the MCP companion for tvsub, an experimental subtitle overlay for Apple TV.app on macOS. It lets an MCP client inspect the current playback item, choose or translate a subtitle file, adjust its appearance, start or stop the overlay, and calibrate subtitle timing.

Supported player: purchased and rented films in macOS Apple TV.app (Prime Video support is being explored and is not currently available). Subtitle formats: SRT, SMI/SAMI, VTT. Translation runs on your choice of three backends: an Anthropic API key, a signed-in Claude Code CLI (Claude subscription), or a signed-in Codex CLI (ChatGPT subscription) — subscription backends add no API charges.

The server does not download subtitles, bypass DRM, modify video, or launch TV.app. You provide subtitle files that you have the right to use and start playback yourself.

Two directions, one workflow

If 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.

Apple TV.app에서 구매한 외화·고전·다국어 영화에 한국어 또는 원하는 언어 자막이 없다면, 정당하게 보유한 자막 파일을 불러와 Claude나 ChatGPT 구독으로 번역한 뒤 오버레이로 표시할 수 있습니다. 같은 방식으로 전 세계 시청자도 한국 영화와 시리즈의 정당하게 보유한 자막을 자신의 언어로 번역해 시청할 수 있습니다.

Requirements

recommended uvx installation

• macOS
• tvsub, installed and built
• Python 3.12 or later
• uv for the

Claude Code CLI (Claude subscription), or a signed-in Codex CLI (ChatGPT subscription). No key or CLI is needed for any other tool

• For subtitle translation, one of: an Anthropic API key, a signed-in

Install and register with Claude Code

Replace /absolute/path/to/tvsub with the directory containing tvsub's build/, config/, src/, and subtitles/ directories.

brew install uv

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

claude mcp get tvsub
claude mcp list

Translation picks a backend automatically: an Anthropic API key if present, then a signed-in Claude Code CLI, then a signed-in Codex CLI. Set TVSUBTRANSLATEBACKEND (auto, api, claude, codex) or the backend tool argument to override. With a subscription CLI signed in you can skip the key entirely. To use the API backend, export your key and include it when registering the server — or store it once in macOS Keychain (service kim.youngji.tvsub.anthropic), which the server also reads.

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.2.2 \
  --tvsub-root /absolute/path/to/tvsub

Other stdio MCP clients can launch the same command:

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

Tools

Shortened. The full README is on GitHub.