tvsub-mcp
Provides tools to inspect the currently playing item in Apple TV.app, manage subtitle files (select, translate, review), control the subtitle overlay appearance, and calibrate subtitle timing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tvsub-mcp Translate the current subtitle to Korean and start the overlay"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 구독으로 번역한 뒤 오버레이로 표시할 수 있습니다. 같은 방식으로 전 세계 시청자도 한국 영화와 시리즈의 정당하게 보유한 자막을 자신의 언어로 번역해 시청할 수 있습니다.
Related MCP server: VisionCLI
Requirements
macOS
tvsub, installed and built
Python 3.12 or later
uvfor the recommendeduvxinstallationFor subtitle translation, one of: an Anthropic API key, a signed-in Claude Code CLI (Claude subscription), or a signed-in Codex CLI (ChatGPT subscription). No key or CLI is needed for any other tool
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.3.0 \
--tvsub-root /absolute/path/to/tvsub
claude mcp get tvsub
claude mcp listTranslation picks a backend automatically: an Anthropic API key if present,
then a signed-in Claude Code CLI, then a signed-in Codex CLI. Set
TVSUB_TRANSLATE_BACKEND (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.3.0 \
--tvsub-root /absolute/path/to/tvsubOther stdio MCP clients can launch the same command:
uvx tvsub-mcp==0.3.0 --tvsub-root /absolute/path/to/tvsubTools
Tool | Purpose |
| Read the current Apple TV.app title, content ID, position, and playback state. |
| List and parse SRT, SMI, SAMI, and VTT files in tvsub's subtitle library. |
| Select a subtitle file for the current content while preserving sync anchors by default. |
| Estimate or perform an LLM translation with cue and timecode validation. Supports backend selection, glossary injection, and partial retranslation by line or time range. |
| Create or update a per-title glossary (names, honorifics, relationships, forbidden translations) that is injected into translation prompts. |
| Promote a translated subtitle's provenance from |
| List installed macOS fonts and check sample glyph coverage. |
| Change font, size, colors, outline, background, and screen position. |
| Start tvsub with the selected subtitle and style. |
| Stop only the overlay process started by this server. |
| Store one or more dialogue anchors and calculate timing offset and drift. |
| Summarize playback, overlay, subtitle, style, and calibration state. |
Before translating, call translate_subtitle with dry_run=true to review the
cue count, batch count, and estimated cost. Subscription backends report
$0 (included in subscription). Every translation writes a .provenance.json
sidecar recording backend, hashes, and review status.
Usage statistics
Starting with 0.2.3, anonymous usage statistics are enabled by default.
The server stores a random installation ID (UUIDv4), daily tool and translation
backend counts, and send dates in
~/Library/Application Support/tvsub/telemetry.json. The first enabled run
prints a notice to stderr; the status tool reports whether collection is enabled,
what is sent, and how to disable it.
On startup and after tool calls, the server checks for unsent days before today.
It sends the oldest pending day in a background POST to
https://youngji.kim/api/tvsub/telemetry, at most once per local calendar day.
The timeout is 3 seconds. Failed attempts keep their counters and retry on the
next eligible day; they do not interrupt tools. TVSUB_TELEMETRY_URL overrides
the collector URL.
The JSON contains only install_id, day, tvsub_mcp_version, macos_version
(major.minor), python_minor (major.minor), tools (counts for the 12 tool names),
and backends (counts for api, claude, codex, pro, or auto). An omitted
or empty backend is counted as auto; this records the requested backend,
not the backend eventually selected by translation. Statistics never include
subtitle text, titles, content IDs, filenames, paths, glossaries, API keys,
raw errors, or IP addresses in the payload.
To disable both recording and sending, set TVSUB_TELEMETRY=0
(false, off, and no also work, case-insensitively), or DO_NOT_TRACK=1
in the MCP server's environment. For example, add --env TVSUB_TELEMETRY=0
to the claude mcp add command before tvsub. Mock mode (--mock or
TVSUB_MCP_MOCK=1) and tests always disable statistics. Disabling leaves any
existing local counters untouched; no statistics are recorded or sent while disabled.
Important notices
Experimental software: expect rough edges and breaking changes. Keep a backup of your tvsub configuration and subtitle files.
Data sent to Anthropic: translation sends the selected subtitle text and surrounding subtitle context to the Anthropic API. Loading, styling, sync, and overlay controls do not send subtitle text to Anthropic.
User-paid API usage: the
apibackend uses your Anthropic API key and all charges are your responsibility; estimates can differ from the final bill. Theclaudeandcodexbackends run through your own signed-in subscription CLIs and add no API charges.Private API risk: tvsub reads Apple playback state through undocumented macOS MediaRemote interfaces. Apple does not support this integration and a macOS update may change or disable it.
Content rights: you are responsible for having the right to process and translate subtitle files. Do not redistribute protected content without permission.
This project is independent from and not affiliated with Apple or Anthropic.
Development
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.shBefore tagging a release, run bash scripts/preflight.sh from the repository root.
Linux can run the unit tests and mock stdio smoke test. Apple TV.app, MediaRemote, CoreText, and the real overlay require macOS.
License
MIT. See LICENSE.
Available Tools
12 toolscalibrate_syncAIdempotent
현재 대사와 일시정지 위치로 영화별 싱크 앵커를 기록하고 2점 scale+offset을 계산합니다. 권장 경로는 spoken_text(지금 들린 대사 일부)입니다. ⚠ subtitle_time은 자막 파일 원본 시각이며, tvsub CLI의 anchor --raw-sub-time과 같은 의미입니다. 화면에 보인 시각(보정 적용 후)을 넣는 anchor --sub-time과 다르므로, 이미 offset이 걸린 상태에서 화면 시각을 넣으면 앵커가 offset만큼 틀어집니다.
Inputs: spoken_text (required), store_id, actual_time, subtitle_time.
list_fontsARead-onlyIdempotent
macOS CoreText 설치 폰트를 열거하고 목표 언어 샘플 글리프 지원 여부를 확인합니다.
Inputs: language.
list_subtitlesARead-onlyIdempotent
tvsub subtitles/ 라이브러리의 SRT/SMI/VTT 파일과 파싱 정보를 나열합니다.
Inputs: no named parameters.
load_subtitleBDestructiveIdempotent
콘텐츠에 사용할 자막을 선택합니다. 기존 싱크 앵커는 기본적으로 보존합니다.
Inputs: subtitle (required), store_id, reset_anchors.
mark_reviewedAIdempotent
번역 SRT의 provenance 상태를 user_reviewed로 갱신합니다.
Inputs: subtitle (required).
now_playingARead-onlyIdempotent
MediaRemote/JXA와 TV.app AppleScript 교차 검증으로 현재 제목, 콘텐츠 ID, 위치와 재생 상태를 조회합니다.
Inputs: no named parameters.
set_glossaryBDestructiveIdempotent
작품 자막 옆 <작품>.glossary.json을 생성·수정합니다.
Inputs: glossary (required), subtitle (required).
set_styleAIdempotent
폰트·크기·색·외곽선·TV 영상 창 하단 위치를 저장하고 실행 중 오버레이에 즉시 반영합니다. outline_width는 pt가 아니라 폰트 크기 대비 퍼센트입니다(5 = 5%). 4~7이 실용 범위이고, 10을 넘기면 글자 속까지 외곽선 색으로 덮여 읽기 어려워집니다. bottom_margin은 TV 영상 창 높이 대비 비율(0.075 = 7.5%)이며 창 취득 실패 때만 화면 기준입니다.
Inputs: color, language, font_size, max_lines, +5 more.
start_overlayBIdempotent
tvsub NSPanel 오버레이를 선택 자막·스타일로 시작합니다. bottom_margin은 TV 영상 창 높이 기준이며 창을 찾지 못할 때만 설정 화면 기준으로 폴백합니다.
Inputs: color, store_id, subtitle, font_size, +3 more.
statusARead-onlyIdempotent
오버레이, 재생 항목, 선택 자막, 싱크 보정, 스타일과 창 기준 위치 추적 계약을 한 번에 요약합니다.
Inputs: no named parameters.
stop_overlayAIdempotent
이 MCP 서버가 시작한 tvsub 오버레이 프로세스를 정상 종료합니다.
Inputs: no named parameters.
translate_subtitleB
Anthropic API, Claude 구독(Claude Code CLI), ChatGPT 구독(Codex CLI) 중 선택해 자막을 번역합니다. backend는 auto/api/claude/codex이며 타임코드·큐 수 검증, 캐시, provenance를 공통 적용합니다.
Inputs: subtitle (required), force, backend, dry_run, +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource and action: subtitle selection vs listing vs translation vs sync calibration are clearly separated. Even similar operations like load_subtitle and list_subtitles have unambiguous purposes.
All tool names follow a consistent verb_noun snake_case pattern (e.g., load_subtitle, list_fonts, calibrate_sync). No mixed conventions or vague verbs.
12 tools is well within the ideal range and each tool covers a distinct aspect of the subtitle overlay workflow: selection, rendering, styling, translation, sync, and status.
Core lifecycle is covered: loading subtitles, starting/stopping overlay, translating, review marking, styling, sync calibration, and status. Minor gaps exist like subtitle deletion or direct subtitle editing, but agents can complete the main workflow without dead ends.
Maintenance
Related MCP Connectors
Search, inspect and download subtitles for movies and TV from OpenSubtitles.com.
712Subtitle engine for AI agents: one upload gives a written track and a translation, timings exact.
Transcribe audio and video, and translate subtitles into 50+ languages.
Convert subtitles, transcripts, broadcast captions (SCC/MCC/STL), EDLs, and Premiere files.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables driving macOS apps from Claude Code — screenshots, accessibility trees, clicks, typing and keys — by borrowing the Computer Use eyes and hands from OpenAI's ChatGPT/Codex desktop app, with persistent JavaScript scripting, text-targeted batching, diff output and macros that collapse many actions into one call without consuming Codex quota or calling a model.2MIT
- AlicenseBqualityBmaintenanceEnables Claude Code and Gemini CLI to see your macOS screen, answering questions about the file, error, UI, database table, or web page you're looking at. Captures screenshots, reads database schemas, and controls Chrome/Brave, presenting answers as on-screen highlights or spoken bubbles above your cursor.31MIT
- AlicenseNot gradedqualityCmaintenanceEnables local voice cloning and multi-take text-to-speech synthesis on Apple Silicon, plus audio/video transcription and subtitle generation, through Claude and other MCP clients.2MIT
- AlicenseAqualityBmaintenanceEnables an AI agent to inspect, repair, retime, convert, merge/split, and search SRT, WebVTT, and ASS subtitle files entirely offline, with exact-fraction resync, dry-run fixes, and honest encoding detection. Translation is handled by the agent itself through a chunk/apply contract that preserves timing and flags lost tags.10MIT