mcp-tvsubtitles

mcp-tvsubtitles

TVsubtitles.net はテレビシリーズの字幕を掲載するサイトです。利用者は各エピソードの字幕ファイルを、特定の動画リリースに合わせてアップロードします。サイトには、言語、字幕が対応するリリース、アップロードした人と日時、ファイルサイズ、ダウンロード回数が記録されています。24言語、約8万6千のエピソードにわたる約30万件の字幕が登録されています。

このサーバーはチャットクライアントをこのカタログに接続します。シリーズを検索したり、シーズンを調べて各エピソードにどの言語の字幕があるかを確認したり、エピソードの字幕記録を一覧したり、字幕が対応するリリースやアップロードした人を含む個別の記録を開いたりできます。各記録には、サイト上のページへのアドレスが記載されています。APIキーもアカウントも必要ありません。

フランス語版

---

インストール

ワンクリックインストール

Claude Code

claude mcp add tvsubtitles -- npx -y mcp-tvsubtitles

mcpServersを読み込む任意のクライアント

{
  "mcpServers": {
    "tvsubtitles": {
      "command": "npx",
      "args": ["-y", "mcp-tvsubtitles"]
    }
  }
}

Dockerを使用する場合

{
  "mcpServers": {
    "tvsubtitles": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/smeet666/mcp-tvsubtitles:1.0.1"]
    }
  }
}

コンテナはhttps://www.tvsubtitles.netに接続し、それ以外には接続しません。

npmを使わずにバンドルを利用する

mcp-tvsubtitles.mcpbを最新リリースからダウンロードし、MCPバンドルをインストールできるホストで開いてください。依存関係が同梱されているため、必要なのはNode 24以降だけです。

できること

• 「tvsubtitlesにSmallvilleのフランス語字幕はありますか？」
• 「Harbour Lightsのシーズン3には、どの言語の字幕がありますか？」
• 「そのシーズンのエピソード7の英語字幕を一覧にしてください。」
• 「その字幕はどのリリースに合わせたもので、誰がアップロードしましたか？」
• 「最終話のポーランド語字幕をダウンロードできるページを探してください。」

ツール

ツール	機能
search_titles	テレビシリーズを名前で検索し、他のツールが使用する ID を返します。
list_subtitles	シーズン全体の字幕、または 1 エピソード分の字幕レコードを読み取ります。
get_subtitle	1 件のレコードと、そのリリース、アップロードしたユーザー、ダウンロードページを読み取ります。
list_languages	カタログに登録されている言語、または特定の番組に登録されている言語を一覧表示します。

search_titles

名前でカタログを検索します。このサイトのカタログに登録されているのはテレビ番組のみのため、 映画を検索すると、回答ではなく拒否が返されます。

引数	型	必須	機能
query	文字列、1～120 文字	はい	シリーズ名、またはその一部です。
media_type	movie | tv | any	いいえ	tv と any はカタログを検索します。movie は拒否されます。
year	整数、1900～2100	いいえ	公開年にこの年が含まれる行に絞り込みます。
limit	整数、1～100、デフォルトは 20	いいえ	表示する行数です。
with_counts	ブール値、デフォルトは false	いいえ	追加で 1 回リクエストを行い、カタログのインデックスから各行の字幕数、エピソード数、シーズン数を読み取ります。

返される内容： 該当するシリーズ。それぞれに、他のツールが使用する id、サイトが公開している 年、旗で示される言語が含まれます。サイトの検索結果には imdb_id と tmdb_id が公開されないため、これらは null です。with_counts で要求されない限り、 subtitle_count、episode_count、season_count は null です。サイトはこれら 3 つの値を 検索結果のページではなくカタログのインデックスで公開しているためです。各値は番組の全シーズンを 合算したもので、その範囲は counts_scope で示されます。各値は個別に読み取られ、 インデックスに行がない番組では 3 つとも null のままです。total_available は、この検索で 返された行数を数え、その値は total_counts で示されます。結果がなくなる年の指定は適用されず、 filters_dropped に記録されます。

list_subtitles

kindで指定される2種類の形式のいずれかで、シリーズに含まれる内容を読み取ります。

引数	型	必須	説明
id	string, 1–12 characters	はい	search_titlesで取得した番組IDです。
season	integer, 1–200	いいえ	省略すると、サイトにある最新シーズンを読み取ります。
episode	integer, 1–500	いいえ	指定すると、そのエピソードのレコードが返されます。
language	string, 1–40 characters	いいえ	list_languagesにある言語を、名前、サイトコード、またはBCP 47タグで指定します。
limit	integer, 1–200, default 40	いいえ	表示する行数です。

返される内容： シーズンのみを指定した場合、kindはcoverageとなり、各行には1つのエピソードが入り、episode_id、サイトが数えた字幕数、何らかの字幕がある言語が含まれます。エピソードを指定した場合、kindはsubtitlesとなり、各行にはget_subtitleで使用するidを含むレコードが入ります。seasonはサイトが提供したシーズン、season_requestedは指定されたシーズンです。最新シーズンを読み取った場合、両者は異なります。seasons_availableには、その番組にあるシーズンが一覧表示されます。字幕がない言語は除外され、絞り込みなしの結果が返され、その言語はfilters_droppedに示されます。

get_subtitle

list_subtitlesが返したIDから、1つのレコードを読み取ります。

引数	型	必須	説明
id	string, 1–12 characters	はい	list_subtitlesが返した字幕IDです。

返される内容： レコードと、ファイルのダウンロードページを開くためのpage_urlです。read_fromは、ここではrecord、list_subtitlesが生成した行ではlistingを示します。これにより、未取得のフィールドとサイトが公開していないフィールドを区別できます。サイトはレコードの個別ページにのみ表示するため、一覧にはfile_name、size_text、commentが含まれません。releasesにはサイトが公開した動画リリースが入り、release_matchはそのいずれかが公開されているかどうかを示します。公開されている場合はstated、公開されていない場合はnoneとなり、noneのレコードからは、どの動画に合わせた字幕なのかは分かりません。uploaderは、およそ3件に2件でnullです。published_atはサイトの日時表記をISO 8601形式に読み取ったもので、タイムゾーン情報は含まれません。published_textにはサイト独自の表記が保持されます。ratingにはサイトが公開する2つのカウンターが入り、ゼロもサイトが表示した数値です。

list_languages

サイトがカタログに登録している言語、または特定の番組にある言語を一覧表示します。

引数	型	必須	説明
id	string, 1–12 characters	いいえ	番組が含む内容を読み取るための番組IDです。
season	integer, 1–200	いいえ	番組のどのシーズンを対象に調べるかを指定します。idがない場合は無視されます。

返される内容： 各言語について、サイトが表示する名前、その言語を指定するための2文字のsite_code、対応関係が確かな場合のBCP 47形式のcode、およびdiffers_from_isoが返されます。scopeは測定対象を示します。サイト全体の場合はcatalogue、番組IDが渡された場合はseasonとなり、その場合、countはそのシーズンでその言語の字幕があるエピソード数です。

言語とサイトで使用されるコード

サイトには24種類の旗が表示されており、それぞれの言語には独自に選んだ2文字のコードが割り当てられています。そのうち6つはISO 639-1とは異なり、1つは重複しています。サイトではブラジルポルトガル語にbrを使用していますが、ISOではこのコードはブルトン語に割り当てられています。

サイトコード	言語	BCP 47
br	ブラジルポルトガル語	pt-BR
gr	ギリシャ語	el
cz	チェコ語	cs
jp	日本語	ja
cn	中国語	zh
ua	ウクライナ語	uk

languageにはサイト独自の名称が入り、language_codeにはタグが入るため、2文字のコードから何かを導き出す必要はありません。list_subtitlesでは、3種類のいずれの表記でも言語を指定できます。

設定

設定は不要です。以下の変数はすべて任意です。

変数	デフォルト	範囲	説明
TVS_USER_AGENT	未設定		このサーバー独自のエージェントの先頭に追加されます。独自のエージェントは引き続き付与されます。
TVS_MIN_INTERVAL_MS	2000	1500–60000	リクエスト間のミリ秒数です。下限は1500です。
TVS_TIMEOUT_MS	20000	1000–120000	1回の試行の期限です。
TVS_BUDGET_MS	60000	5000–600000	再試行を含む、1回の読み取りの期限です。
TVS_MAX_RETRIES	3	0–8	初回の後に行う試行回数です。
TVS_CACHE_TTL_MS	900000	0–86400000	ページをメモリに保持する期間です。0にするとストアが無効になります。
TVS_CACHE_MAX_ENTRIES	200	1–5000	最も長く使われていないページが削除されるまでに保持するページ数です。
TVS_MAX_BODY_BYTES	8000000	100000–64000000	1ページで読み取るレスポンスの最大サイズです。
TVS_LOG_LEVEL	error	silent、error、info、debug	stderrに出力する内容です。

範囲外の値はstderrに警告を出して拒否され、デフォルト値が適用されます。

エラー

コード	意味	対処方法
not_found	サイトから応答がありましたが、その項目は存在しません。	IDを手入力ではなく、一覧から取得したか確認してください。
invalid_input	引数からリクエストを作成できませんでした。	引数名が記載されたメッセージを確認してください。
rate_limited	サイトから、このクライアントに速度を落とすよう求められました。	待ってから再試行してください。要求した項目は引き続き存在します。
parse_failure	読み取りできない形式のレスポンスが届きました。	使用した引数とともに報告してください。
network_error	リクエストが完了しませんでした。	再試行してください。
timeout	期限内に応答がありませんでした。	再試行するか、TVS_BUDGET_MSを増やしてください。

ライブラリとして

サイトを読み取るレイヤーは、リクエスト間隔の制御、ストア、エラーコードを含み、プロトコルに依存しない形で単独で公開されています。

import { TvSubtitlesClient } from "mcp-tvsubtitles/client";

const client = new TvSubtitlesClient();
const found = await client.searchShows("Smallville");
const season = await client.getSeason(found.data.rows[0].id, 0);
console.log(season.data.showName, season.data.season, season.data.episodes.length);

読み取りの戻り値はすべて{ data, cached }です。行が省略された場合はskippedも含まれます。コンストラクターには{ config, logger, fetchImpl }を渡し、間隔の下限は渡された値に適用されます。

リクエスト間隔とクレジット表記

リクエストは一度に1件ずつ、2秒間隔で送信します。サイトから制限を受けた場合は間隔を広げ、応答が続けて正常なら再び狭めます。間隔は最低でも1.5秒で、これより短くすることはできません。エージェント文字列には、プロジェクト名、バージョン、リポジトリのアドレスが含まれているため、サイトから担当者に連絡できます。

字幕は、作成しタイミングを合わせた人たちの作品です。このサーバーはカタログを読み取るだけで、字幕ファイルはダウンロードしません。各レコードには page_url が含まれており、これは読者が字幕をダウンロードするために開くページです。結果を表示する際は tvsubtitles.net にクレジットを付け、そのページへのリンクを掲載してください。

この MCP サーバーは tvsubtitles.net とは提携していません。

プライバシー

アカウントもキーもテレメトリーも不要です。アクセスするホストは https://www.tvsubtitles.net だけです。ページは15分間メモリに保持され、ディスクには何も書き込まれません。診断情報は stderr に出力されます。PRIVACY.md をご覧ください。

開発

npm install
npm run build:fixtures
npm test
npm run coverage
npm run check

npm run test:live はサイトの各ルートに対して1件ずつリクエストを送信し、毎晩実行されます。

コントリビューション

Issue とプルリクエストを歓迎します。CONTRIBUTING.md と SECURITY.md をご覧ください。

ライセンス

MIT。LICENSE をご覧ください。

---

mcp-tvsubtitles（フランス語）

英語版

TVsubtitles.net は、テレビシリーズの字幕をカタログ化しています。利用者は各エピソードの動画バージョンに合わせた字幕ファイルを投稿します。サイトには、言語、字幕が合わせられたバージョン、投稿者、投稿日時、ファイルサイズ、ダウンロード回数が記録されます。約8万6千のエピソードに対し、24言語でおよそ30万件の字幕が登録されています。

このサーバーは、会話型クライアントをこのカタログに接続します。シリーズを検索したり、各エピソードでどの言語の字幕があるかを確認しながらシーズンを閲覧したり、エピソードの字幕情報を読んだり、字幕が合わせられたバージョンや投稿者を確認したりできます。各字幕情報には、サイト上のページアドレスが含まれています。API キーもアカウントも必要ありません。

インストール

ワンクリックインストール

Claude Code

claude mcp add tvsubtitles -- npx -y mcp-tvsubtitles

mcpServers を読み込むすべてのクライアント

{
  "mcpServers": {
    "tvsubtitles": {
      "command": "npx",
      "args": ["-y", "mcp-tvsubtitles"]
    }
  }
}

Docker を使用する場合

{
  "mcpServers": {
    "tvsubtitles": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/smeet666/mcp-tvsubtitles:1.0.1"]
    }
  }
}

コンテナが接続するのは https://www.tvsubtitles.net だけです。

npm を使わないバンドル

最新のリリースから mcp-tvsubtitles.mcpb をダウンロードし、MCP バンドルをインストールするホストで開いてください。依存関係が同梱されているため、Node 24 以降があれば十分です。

できること

• 「tvsubtitles に Smallville のフランス語字幕はありますか？」
• 「Harbour Lights のシーズン3では、どの言語の字幕がそろっていますか？」
• 「このシーズンのエピソード7にある英語字幕を一覧表示してください。」
• 「この字幕はどのバージョンに合わせられていますか？また、誰が投稿しましたか？」
• 「最終話のポーランド語字幕をダウンロードできるページを探してください。」

ツール

ツール	機能
search_titles	シリーズを名前で検索し、ほかのツールが使用する ID を返します。
list_subtitles	シーズンの一覧、またはエピソードの詳細を読み込みます。
get_subtitle	詳細を読み込み、バージョン、投稿者、ダウンロードページを返します。
list_languages	カタログの言語、またはシリーズにある言語を一覧表示します。

search_titles

名前でカタログを検索します。このサイトがカタログに登録しているのはテレビ番組のみ なので、映画の検索には回答せず、拒否します。

引数	型	必須	機能
query	文字列、1～120 文字	はい	シリーズ名、またはその一部です。
media_type	movie | tv | any	いいえ	tv と any はカタログを検索します。movie は拒否されます。
year	整数、1900～2100	いいえ	公開年に指定した年が含まれる行に絞り込みます。
limit	整数、1～100、既定値 20	いいえ	返す行数です。
with_counts	ブール値、既定値は false	いいえ	カタログのインデックスから各行の字幕、エピソード、シーズンの件数を読み込みます。その分、リクエストが 1 回増えます。

返される内容： 見つかったシリーズ。それぞれに、ほかのツールが使用するid、 サイトに掲載されている公開年、旗が表示される言語が含まれます。サイトの検索結果には 掲載されないため、imdb_id と tmdb_id は null です。サイトは字幕、エピソード、 シーズンの 3 つの件数を検索結果ページではなくカタログのインデックスに掲載している ため、with_counts で要求されない限り、subtitle_count、episode_count、 season_count は null です。各件数はシリーズの全シーズンをまとめて数えたもので、 その対象範囲は counts_scope に示されます。各件数は個別に読み込まれ、インデックスに 行がないシリーズでは 3 つとも null のままです。total_available はこの検索で 取得した行数を数え、その定義は total_counts に示されます。該当結果のない年は 除外され、filters_dropped に記載されます。

list_subtitles

kindで指定される2種類の形式のいずれかで、シリーズが保持している内容を読み取ります。

引数	型	必須	説明
id	文字列、1～12文字	はい	search_titlesから取得したシリーズIDです。
season	整数、1～200	いいえ	省略すると、最新シーズンを読み取ります。
episode	整数、1～500	いいえ	指定すると、そのエピソードの字幕レコードを返します。
language	文字列、1～40文字	いいえ	list_languagesにある言語を、名前、コード、またはBCP 47タグで指定します。
limit	整数、1～200、デフォルト40	いいえ	返す行数です。

戻り値： シーズンのみを指定した場合、kindはcoverageとなり、各行はエピソードを表します。各行にはepisode_id、サイトが数える字幕の件数、字幕がある言語が含まれます。エピソードを指定した場合、kindはsubtitlesとなり、各行はget_subtitleで使用するidを持つ字幕レコードを表します。seasonはサイトが返したシーズンで、season_requestedは要求されたシーズンです。最新シーズンが読み取られた場合、この2つは異なります。seasons_availableには、そのシリーズが保持するシーズンが一覧表示されます。字幕がない言語は除外され、制限なしで応答が返され、その言語はfilters_droppedに記載されます。

get_subtitle

list_subtitlesが返したIDから字幕レコードを読み取ります。

引数	型	必須	説明
id	文字列、1～12文字	はい	list_subtitlesから取得した字幕IDです。

戻り値： 字幕レコードと、読者がファイルをダウンロードするために開くページのpage_urlが返されます。ここではread_fromはrecordで、list_subtitlesの行から取得した場合はlistingです。これにより、読み取られていないフィールドと、サイトが公開していないフィールドを区別できます。リストにはfile_name、size_text、commentが含まれず、これらはサイトが字幕レコードのページにのみ表示します。releasesにはサイトが公開した動画リリースが含まれ、release_matchはサイトが該当するリリースを公開しているかどうかを示します。公開している場合はstated、していない場合はnoneとなります。そのため、noneの字幕レコードは、どの動画に対応しているかを示すものではありません。約3分の2の字幕レコードで、uploaderはnullです。published_atはサイトのタイムスタンプをISO 8601形式で読み取ったもので、タイムゾーン情報は含まれません。published_textにはサイトの表記がそのまま保持されます。ratingにはサイトが公開する2つのカウンターが含まれ、ゼロもサイトに表示された値です。

list_languages

サイトがカタログに登録している言語、またはシリーズが保持している言語を一覧表示します。

引数	型	必須	説明
id	文字列、1～12文字	いいえ	シリーズが保持している内容を読み取るためのシリーズIDです。
season	整数、1～200	いいえ	対象とするシーズンです。idがない場合は無視されます。

戻り値： 各言語について、サイトに表示される名前、サイトが使用する2文字のsite_code、対応が確実な場合はBCP 47のcode、およびdiffers_from_isoが返されます。scopeは測定対象を示します。サイト全体の場合はcatalogue、シリーズIDが渡されている場合はseasonとなり、その場合のcountは、そのシーズンでその言語を保持するエピソード数です。

言語とサイトのコード

サイトでは24種類の旗が表示され、それぞれの言語には独自に選んだ2文字のコードが割り当てられています。6つのコードはISO 639-1と異なり、そのうち1つは衝突しています。サイトではブラジルポルトガル語にbrを使っていますが、ISOではブルトン語に割り当てられています。

サイトコード	言語	BCP 47
br	ブラジルポルトガル語	pt-BR
gr	ギリシャ語	el
cz	チェコ語	cs
jp	日本語	ja
cn	中国語	zh
ua	ウクライナ語	uk

languageにはサイトでの名前が入り、language_codeにはタグが入るため、2文字から何かを推測する必要はありません。list_subtitlesでは、言語を3通りのいずれかの形式で指定できます。

設定

設定は不要です。以下の変数はすべてオプションです。

変数	デフォルト	範囲	機能
TVS_USER_AGENT	なし		サーバーのユーザーエージェントの前に追加されます。サーバーのユーザーエージェントはそのまま付加されます。
TVS_MIN_INTERVAL_MS	2000	1500～60000	リクエスト間の間隔（ミリ秒）。1500が下限です。
TVS_TIMEOUT_MS	20000	1000～120000	1回の試行のタイムアウト。
TVS_BUDGET_MS	60000	5000～600000	再試行を含む、読み取りのタイムアウト。
TVS_MAX_RETRIES	3	0～8	初回の後に行う再試行の回数。
TVS_CACHE_TTL_MS	900000	0～86400000	ページをメモリに保持する期間。0にするとキャッシュが無効になります。
TVS_CACHE_MAX_ENTRIES	200	1～5000	最も古いページが削除されるまでに保持するページ数。
TVS_MAX_BODY_BYTES	8000000	100000～64000000	ページごとに読み取るレスポンスの最大サイズ。
TVS_LOG_LEVEL	error	silent、error、info、debug	stderrに出力する内容。

範囲外の値は拒否され、その旨がstderrに出力されます。その場合はデフォルト値が適用されます。

エラー

コード	意味	対処方法
not_found	サイトは応答しましたが、その項目はありません。	IDが作成したものではなく、リストから取得したものか確認してください。
invalid_input	引数からリクエストを作成できません。	引数名が記載されたメッセージを確認してください。
rate_limited	サイトがこのクライアントに速度を落とすよう求めています。	待ってから再度リクエストしてください。要求した項目は引き続き存在します。
parse_failure	読み取れない形式のレスポンスが届きました。	使用した引数とともに報告してください。
network_error	リクエストが完了しませんでした。	再試行してください。
timeout	制限時間内にレスポンスがありませんでした。	再試行するか、TVS_BUDGET_MSを大きくしてください。

ライブラリとして

サイトを読み取る層は、プロトコルに依存せず、独自のリズム、キャッシュ、エラーコードを備えた単独のパッケージとして公開されています。

import { TvSubtitlesClient } from "mcp-tvsubtitles/client";

const client = new TvSubtitlesClient();
const found = await client.searchShows("Smallville");
const season = await client.getSeason(found.data.rows[0].id, 0);
console.log(season.data.showName, season.data.season, season.data.episodes.length);

読み取りではすべて { data, cached } が返され、行が除外された場合は skipped も返されます。コンストラクターには { config, logger, fetchImpl } を渡します。渡された値にかかわらず、インターバルの下限は維持されます。

リズムとクレジット表記

一度にリクエストは1件で、間隔は2秒です。サイトから拒否された場合は間隔を広げ、問題のない応答が続いた後は短くします。1.5秒の下限は引き下げられません。エージェント文字列にはプロジェクト名、バージョン、リポジトリのアドレスが含まれており、サイトから担当者に連絡できます。

字幕は、作成してタイミングを合わせた人たちの作品です。このサーバーはカタログを読み取りますが、字幕ファイルはダウンロードしません。各項目には、読者がダウンロードのために開くページである page_url が含まれています。結果を表示する際は、tvsubtitles.net をクレジット表記し、このページへのリンクを付けてください。

この MCP サーバーは tvsubtitles.net と提携していません。

プライバシー

アカウント、キー、テレメトリーはありません。接続するホストは https://www.tvsubtitles.net だけです。ページはメモリーに15分間保持され、ディスクには何も書き込まれません。診断情報は stderr に出力されます。PRIVACY.md をご覧ください。

開発

npm install
npm run build:fixtures
npm test
npm run coverage
npm run check

npm run test:live はサイトの各ルートに対して1件ずつリクエストを行い、毎晩実行されます。

貢献

イシューやプルリクエストを歓迎します。CONTRIBUTING.md と SECURITY.md をご覧ください。

ライセンス

MIT。LICENSE をご覧ください。