Skip to content
MCP server

tvsub MCP

Drive the tvsub subtitle overlay for Apple TV.app: load, translate, style, sync

Runs locallyStatus and history
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-mcp

Add 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

  1. Wuai

    MCP server

    Answers questions about Wuai, a free on-device caption and translation app for videos

    • 7 tools
    • Remote
    • Freemium
    • Design and media
  2. MaineMCP

    MCP server

    Search public Maine events, communities and startups, with links to the source listings

    • 4 tools
    • Remote
    • Free
    • Events and entertainment
  3. FreeDict

    MCP server

    Dictionary lookups, synonyms, rhymes, slang and word search for AI apps and games

    Not checked yet
    • Remote
    • Freemium
    • Language learning
  4. NYC-area event vendor prices, areas and booking options sourced from vendor sites

    • 9 tools
    • Remote
    • Free
    • Events and entertainment
  5. Tap2Cal

    MCP server

    Create shareable add-to-calendar links and read RSVPs from your AI assistant

    Not checked yet
    • 9 tools
    • Remote
    • Free
    • Productivity
  6. Correct and translate Aranese text following the IEA norm, free and without a key

    • 4 tools
    • Remote
    • Free
    • Language learning