tvsub MCP

tvsub MCP

tvsub-mcpは、macOSのApple TV.app向けの実験的な字幕オーバーレイであるtvsubのMCP連携ツールです。MCPクライアントから、現在の再生項目の確認、字幕ファイルの選択や翻訳、表示の調整、オーバーレイの開始や停止、字幕タイミングの調整ができます。

対応プレーヤー：macOSのApple TV.appで購入またはレンタルした映画 （Prime Videoへの対応は検討中で、現在は利用できません）。 字幕形式：SRT、SMI/SAMI、VTT。翻訳には、Anthropic APIキー、サインイン済みのClaude Code CLI（Claudeのサブスクリプション）、サインイン済みのCodex CLI（ChatGPTのサブスクリプション）の3つのバックエンドから選択できます。サブスクリプションのバックエンドでは、API料金はかかりません。

このサーバーは、字幕をダウンロードしたり、DRMを回避したり、動画を変更したり、TV.appを起動したりしません。利用する権利のある字幕ファイルを用意し、ご自身で再生を開始してください。

2つの方向、1つのワークフロー

Apple TV.appで購入した外国映画、古典映画、多言語映画に韓国語や必要な言語の字幕がない場合は、正当に入手した字幕ファイルを用意し、ClaudeまたはChatGPTのサブスクリプションで翻訳して、オーバーレイとして表示できます。同じワークフローで、世界中の視聴者が韓国映画やシリーズの正当に入手した字幕を自分の言語に翻訳することもできます。

必要条件

• macOS
• インストールしてビルド済みのtvsub
• Python 3.12以降
• 推奨されるuvxインストールに必要なuv
• 字幕の翻訳には、Anthropic APIキー、サインイン済みのClaude Code CLI（Claudeのサブスクリプション）、サインイン済みのCodex CLI（ChatGPTのサブスクリプション）のいずれかが必要です。その他のツールには、キーもCLIも必要ありません

Claude Codeへのインストールと登録

/absolute/path/to/tvsubを、tvsubのbuild/、config/、src/、subtitles/ディレクトリが含まれるディレクトリに置き換えてください。

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 list

翻訳バックエンドは自動的に選択されます。Anthropic APIキーがあればそれを使用し、次にサインイン済みのClaude Code CLI、続いてサインイン済みのCodex CLIを使用します。TVSUB_TRANSLATE_BACKEND（auto、api、claude、codex）またはbackendツール引数を設定すると、選択を上書きできます。サブスクリプションのCLIにサインインしていれば、キーは不要です。APIバックエンドを使用するには、キーを環境変数に設定してサーバーの登録時に指定してください。または、macOS Keychain（サービス名kim.youngji.tvsub.anthropic）に一度保存すると、サーバーがそこから読み込みます。

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/tvsub

ほかのstdio MCPクライアントからも、同じコマンドを起動できます。

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

ツール

ツール	目的
now_playing	現在の Apple TV.app のタイトル、コンテンツ ID、再生位置、再生状態を読み取ります。
list_subtitles	tvsub の字幕ライブラリにある SRT、SMI、SAMI、VTT ファイルを一覧表示し、解析します。
load_subtitle	デフォルトでは同期アンカーを保持したまま、現在のコンテンツ用の字幕ファイルを選択します。
translate_subtitle	キューとタイムコードの検証を行い、LLM 翻訳の見積もりまたは実行を行います。バックエンドの選択、用語集の挿入、行または時間範囲を指定した部分的な再翻訳に対応しています。
set_glossary	タイトルごとの用語集（名前、敬称、関係性、禁止する訳語）を作成または更新し、翻訳プロンプトに挿入します。
mark_reviewed	翻訳済み字幕の来歴を ai_draft から user_reviewed に変更します。
list_fonts	インストール済みの macOS フォントを一覧表示し、サンプル文字のグリフ対応状況を確認します。
set_style	フォント、サイズ、色、輪郭、背景、画面上の位置を変更します。
start_overlay	選択した字幕とスタイルで tvsub を起動します。
stop_overlay	このサーバーが起動したオーバーレイプロセスのみを停止します。
calibrate_sync	1 つ以上の会話アンカーを保存し、タイミングのオフセットとずれを算出します。
status	再生、オーバーレイ、字幕、スタイル、キャリブレーションの状態を要約します。

翻訳の前に translate_subtitle を dry_run=true で呼び出し、キュー数、 バッチ数、推定コストを確認してください。サブスクリプションのバックエンドでは $0 (サブスクリプションに含まれています) と表示されます。翻訳を行うたびに、 バックエンド、ハッシュ、レビュー状況を記録する .provenance.json サイドカーファイルが書き込まれます。

使用統計

0.2.3 以降、匿名の使用統計はデフォルトで有効です。 サーバーはランダムなインストール ID（UUIDv4）、日ごとのツールと翻訳バックエンドの呼び出し数、 送信日を ~/Library/Application Support/tvsub/telemetry.json に保存します。初回の有効な実行時には stderr に通知が表示され、status ツールで収集が有効かどうか、送信される内容、 無効にする方法を確認できます。

起動時およびツール呼び出し後、サーバーは今日より前の未送信日を確認します。 最も古い未送信日のデータをバックグラウンドで https://youngji.kim/api/tvsub/telemetry に POST します。送信は現地時間で 1 日あたり最大 1 回です。タイムアウトは 3 秒です。失敗した場合もカウンターは保持され、 次に送信可能な日に再試行されます。ツールの実行が中断されることはありません。 TVSUB_TELEMETRY_URL で送信先 URL を上書きできます。

JSON に含まれるのは install_id、day、tvsub_mcp_version、macos_version （major.minor）、python_minor（major.minor）、tools（12 種類のツール名ごとの呼び出し数）、 backends（api、claude、codex、pro、auto ごとの呼び出し数）のみです。バックエンドが省略または空の場合は auto として集計されます。記録されるのはリクエストされたバックエンドであり、 翻訳時に最終的に選択されたバックエンドではありません。統計データのペイロードに 字幕テキスト、タイトル、コンテンツ ID、ファイル名、パス、用語集、API キー、 生のエラー、IP アドレスが含まれることはありません。

記録と送信の両方を無効にするには、TVSUB_TELEMETRY=0 （大文字と小文字を区別せず、false、off、no も使用できます）、または MCP サーバーの環境変数に DO_NOT_TRACK=1 を設定します。たとえば、claude mcp add コマンドの tvsub の前に --env TVSUB_TELEMETRY=0 を追加します。モックモード（--mock または TVSUB_MCP_MOCK=1）とテストでは、統計は常に無効になります。無効にしても 既存のローカルカウンターはそのまま残ります。無効な間は統計の記録も送信も行われません。

重要なお知らせ

• **実験的なソフトウェアです：**未完成の部分や、互換性を損なう変更が発生する可能性があります。tvsub の設定と字幕ファイルのバックアップを保管してください。
• **Anthropic に送信されるデータ：**翻訳時には、選択した字幕テキストと前後の字幕コンテキストが Anthropic API に送信されます。読み込み、スタイル設定、同期、オーバーレイの操作では、字幕テキストは Anthropic に送信されません。
• API の利用料金はユーザー負担です：api バックエンドはお客様の Anthropic API キーを使用し、すべての料金はお客様の負担となります。見積もり額と最終的な請求額は異なる場合があります。claude と codex バックエンドは、お客様がサインインしたサブスクリプションの CLI を通じて動作するため、API 料金は発生しません。
• **非公開 API のリスク：**tvsub は、非公開の macOS MediaRemote インターフェースを通じて Apple の再生状態を読み取ります。Apple はこの連携をサポートしていないため、macOS のアップデートによって変更または無効化される可能性があります。
• **コンテンツの権利：**字幕ファイルを処理および翻訳する権利を有していることは、お客様の責任です。許可なく保護対象のコンテンツを再配布しないでください。
• このプロジェクトは独立しており、Apple または Anthropic とは提携していません。

開発

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

リリースにタグを付ける前に、リポジトリのルートから bash scripts/preflight.sh を実行してください。

Linux では、ユニットテストと stdio のモックを使ったスモークテストを実行できます。Apple TV.app、MediaRemote、CoreText、および実際のオーバーレイには macOS が必要です。

ライセンス

MIT です。LICENSE を参照してください。