tvsub MCP
Drive the tvsub subtitle overlay for Apple TV.app: load, translate, style, sync
- Pricing
- Open source
- Platforms
- macOS, CLI
- Runs
- Locally
- Version
- 0.3.0
- Listing updated
- 2 days ago
About tvsub MCP
tvsub MCP is an open-source MCP server for language learning. It runs locally on your machine and is started by your AI client.
This is the optional automation companion to tvsub, an experimental macOS app that shows a transparent subtitle overlay over films bought or rented in Apple TV.app. It does not download subtitles, bypass DRM, modify the video or launch the TV app; you supply subtitle files you have the right to use and start playback yourself. Supported formats are SRT, SMI/SAMI and VTT, and Prime Video is not supported.
Through the server an assistant can read the current title and playback position, choose a subtitle file from the library, translate it, keep a per-title glossary of names, honorifics and relationships that is injected into translation prompts, mark a translation as reviewed, and calibrate sync. Translation checks cue IDs, cue count and timecodes before saving, and supports partial retranslation by line or time range. The site notes that machine output can miss honorifics and wordplay and should be reviewed.
Translation runs on an Anthropic API key, a signed-in Claude Code CLI or a signed-in Codex CLI, chosen automatically unless overridden. Subscription backends add no API charges. Setup needs Python 3.12 or later, uv and a built tvsub.
Install
Run in a terminal
claude mcp add tvsub-mcp --env ANTHROPIC_API_KEY='<ANTHROPIC_API_KEY>' -- uvx tvsub-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"tvsub-mcp": {
"command": "uvx",
"args": [
"tvsub-mcp"
],
"env": {
"ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"tvsub-mcp": {
"command": "uvx",
"args": [
"tvsub-mcp"
],
"env": {
"ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"tvsub-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"tvsub-mcp"
],
"env": {
"ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"tvsub-mcp": {
"command": "uvx",
"args": [
"tvsub-mcp"
],
"env": {
"ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"tvsub-mcp": {
"command": "uvx",
"args": [
"tvsub-mcp"
],
"env": {
"ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
}
}
}
}Configuration
ANTHROPIC_API_KEYAnthropic API key; required only for subtitle translation
Tools this server provides (6)
Taken from the project documentation; the running server may differ.
- now_playing
- Reads the current Apple TV.app title, content ID, position and playback state.
- list_subtitles
- Lists and parses SRT, SMI, SAMI and VTT files in the subtitle library.
- load_subtitle
- Selects a subtitle file for the current content, keeping sync anchors by default.
- translate_subtitle
- Estimates or performs LLM translation with glossary injection and partial retranslation.
- set_glossary
- Creates or updates a per-title glossary used in translation prompts.
- mark_reviewed
- Promotes a translated subtitle's provenance from ai_draft to reviewed.
What it does
- Playback awareness
- Reads the current Apple TV.app title, position and state.
- Subtitle translation
- Estimates and runs LLM translation with cue and timecode validation.
- Per-title glossary
- Keeps names, honorifics and forbidden translations for consistent output.
- Provenance review
- Moves a translation from AI draft to reviewed.
- Backend choice
- Uses an Anthropic key, Claude subscription or ChatGPT subscription.
- Sync calibration
- Adjusts subtitle timing and appearance of the overlay.
Good for
- Translate a Korean subtitle file into your own language
- Add Korean subtitles to a foreign film bought in Apple TV.app
- Keep character names consistent across an episode series
- Retranslate a few lines after spotting a mistake
- Fix subtitle timing that drifts from the scene
Pricing
Open source
Translation uses your own API key or subscription
Prices change. Check youngji.kim before you buy.
tvsub MCP FAQ
Does it work with streaming services?
Only purchased and rented films in macOS Apple TV.app are supported; Prime Video is being explored.
Does it get subtitles for me?
No. It does not download subtitles; you bring files you are entitled to use.
Does it circumvent DRM?
No. The video stays inside Apple TV.app and is not decrypted, copied or altered.
What does translation need?
An Anthropic API key, or a signed-in Claude Code or Codex CLI with a subscription.
Which subtitle formats work?
SRT, SMI/SAMI and VTT.
Is tvsub MCP free?
Yes. tvsub MCP is open source, so you can use and self-host it for free.
How do I add tvsub MCP to Claude Code?
Run this command in your terminal: claude mcp add tvsub-mcp --env ANTHROPIC_API_KEY='<ANTHROPIC_API_KEY>' -- uvx tvsub-mcp
What are the best alternatives to tvsub MCP?
The closest alternatives to tvsub MCP are Wuai, MaineMCP, FreeDict, Agent Bookability Index and Tap2Cal.
Alternatives to tvsub MCP

Wuai
MCP serverAnswers questions about Wuai, a free on-device caption and translation app for videos
- 7 tools
- Remote
- Freemium
- Design and media

MaineMCP
MCP serverSearch public Maine events, communities and startups, with links to the source listings
- 4 tools
- Remote
- Free
- Events and entertainment

FreeDict
MCP serverDictionary lookups, synonyms, rhymes, slang and word search for AI apps and games
Not checked yet- Remote
- Freemium
- Language learning
Agent Bookability Index
MCP serverNYC-area event vendor prices, areas and booking options sourced from vendor sites
- 9 tools
- Remote
- Free
- Events and entertainment
Tap2Cal
MCP serverCreate shareable add-to-calendar links and read RSVPs from your AI assistant
Not checked yet- 9 tools
- Remote
- Free
- Productivity

A punt · Aranese (Val d'Aran Occitan)
MCP serverCorrect and translate Aranese text following the IEA norm, free and without a key
- 4 tools
- Remote
- Free
- Language learning