# tvsub MCP

> tvsub MCP is an open-source MCP server for language learning. Drive the tvsub subtitle overlay for Apple TV.app: load, translate, style, sync. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** macOS, CLI
- **Website:** https://youngji.kim/tvsub
- **Repository:** https://github.com/launzi/tvsub-mcp
- **MCP Registry name:** io.github.launzi/tvsub-mcp
- **Categories:** language learning, events and entertainment
- **Listing updated:** 2026-11-15

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add tvsub-mcp --env ANTHROPIC_API_KEY='<ANTHROPIC_API_KEY>' -- uvx tvsub-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "tvsub-mcp": {
      "command": "uvx",
      "args": [
        "tvsub-mcp"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "tvsub-mcp": {
      "command": "uvx",
      "args": [
        "tvsub-mcp"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "tvsub-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "tvsub-mcp"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "tvsub-mcp": {
      "command": "uvx",
      "args": [
        "tvsub-mcp"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "tvsub-mcp": {
      "command": "uvx",
      "args": [
        "tvsub-mcp"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>"
      }
    }
  }
}
```

## Tools

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

## 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

- [Wuai](https://ai-powered.com/mcp/wuai): Wuai is a freemium MCP server for design and media.
- [MaineMCP](https://ai-powered.com/mcp/mainemcp): MaineMCP is a free MCP server for events and entertainment.
- [FreeDict](https://ai-powered.com/mcp/freedict): FreeDict is a freemium MCP server for language learning.
- [Agent Bookability Index](https://ai-powered.com/mcp/agent-bookability-index): Agent Bookability Index is a free MCP server for events and entertainment.
- [Tap2Cal](https://ai-powered.com/mcp/tap2cal): Tap2Cal is a free MCP server for productivity.
- [A punt · Aranese (Val d'Aran Occitan)](https://ai-powered.com/mcp/a-punt-aranese-val-d-aran-occitan): A punt · Aranese (Val d'Aran Occitan) is a free MCP server for language learning.
- [Veseljko katalog usluga za proslave](https://ai-powered.com/mcp/veseljko-katalog-usluga-za-proslave): Veseljko katalog usluga za proslave is a free MCP server for events and entertainment.
- [숏츠생성기 Free K-pop Shorts](https://ai-powered.com/mcp/free-k-pop-shorts): 숏츠생성기 Free K-pop Shorts is a free MCP server for design and media.

---
Source: https://ai-powered.com/mcp/tvsub-mcp
