mcp-tvsubtitles

TVsubtitles.net catalogues subtitles for

television series. Its readers upload a file for one episode, timed to one video

release, and the site records the language, the release it was cut for, who

uploaded it and when, how large the file is and how often it has been taken. It

holds around three hundred thousand of them, across some eighty-six thousand

episodes in twenty-four languages.

This server connects a chat client to that catalogue. You can search for a

series, read a season and see which languages hold something for each episode,

read the records of one episode, and open one record with the release it was cut

for and who uploaded it. Every record carries the address of its page on the

site. No API key and no account are needed.

_Version française_

Install

One-click install

Claude Code

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

Any client reading `mcpServers`

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

With Docker

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

The container reaches `https://www.tvsubtitles.net` and nothing else.

Bundle, without npm

Download `mcp-tvsubtitles.mcpb` from the

latest release and

open it with a host that installs MCP bundles. It carries its dependencies, so

Node 24 or later is all it needs.

What you can ask

• "Does tvsubtitles have French subtitles for Smallville?"
• "Which languages cover season 3 of Harbour Lights?"
• "List the English subtitles for episode 7 of that season."
• "Which release is that subtitle timed to, and who uploaded it?"
• "Find me the page to download the Polish subtitle for the finale."

Tools

`search_titles`

Searches the catalogue by name. The site catalogues television only, so a search

for a film is refused rather than answered.

In return: the matching series, each with the `id` the other tools take, the

years the site publishes, and the languages it draws a flag for. `imdb_id` and

`tmdb_id` are null, because the site's search publishes none. `subtitle_count`,

`episode_count` and `season_count` are null unless `with_counts` asks for them,

since the site publishes those three on its catalogue index rather than on the

page a search answers with; each counts every season of the show together, which

`counts_scope` names, each is read on its own, and a show the index carries no

row for keeps three nulls. `total_available` counts the rows this one search came

back with, which `total_counts` names. A year that leaves nothing is set aside

and named in `filters_dropped`.

`list_subtitles`

Reads what a series holds, in one of two shapes that `kind` names.

In return: with a season alone, `kind` reads `coverage` and each row is one

episode, carrying `episode_id`, the number of subtitles the site counts and the

languages holding something. With an episode named, `kind` reads `subtitles` and

each row is a record carrying the `id` that `get_subtitle` takes. `season` is the

season the site served and `season_requested` the one that was asked for, which

differ when the newest was read. `seasons_available` lists the seasons the show

holds. A language holding nothing is set aside, the answer comes back

unnarrowed, and `filters_dropped` names it.

`get_subtitle`

Reads one record from an id `list_subtitles` returned.

In return: the record, with `page_url` for the page a reader opens to

download the file. `read_from` reads `record` here and `listing` on a row

`list_subtitles` produced, which is what tells an unread field from one the site

does not publish: a listing carries no `file_name`, no `size_text` and no

`comment`, because the site prints those on a record's own page alone. `releases` holds the video releases the site published and

`release_match` says whether it published any: `stated` where it did, `none`

where it did not, so a record marked `none` says nothing about which video it is

timed to. `uploader` is null on roughly two records out of three. `published_at`

is the site's stamp read into ISO 8601 and carries no timezone, and

`published_text` keeps the site's own wording. `rating` holds two counters the

site publishes, where a zero is a figure it printed.

`list_languages`

Lists the languages the site catalogues, or the ones one show holds.

In return: each language with the name the site prints, the two-letter

`site_code` it addresses the language by, the BCP 47 `code` where that mapping is

certain, and `differs_from_iso`. `scope` says what was measured: `catalogue` for

the whole site, or `season` when a show id was passed, and `count` is then the

episodes of that season holding the language.

Languages, and the codes the site uses

The site draws twenty-four flags and addresses each language by two letters of

its own choosing. Six of them differ from ISO 639-1, and one collides: the site

writes `br` for Brazilian Portuguese, which ISO assigns to Breton.

`language` keeps the site's own name and `language_code` carries the tag, so

nothing has to be derived from the two letters. `list_subtitles` accepts a

language written any of the three ways.

Configuration

Nothing has to be set. Every variable below is optional.

A value outside its range is refused on stderr and the default stands.

Errors

As a library

The layer that reads the site is published on its own, with the pacing, the

store and the error codes, and no protocol attached.

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);

Every read returns `{ data, cached }`, with `skipped` when rows were left out.

The constructor takes `{ config, logger, fetchImpl }`, and the interval floor

holds whatever is passed.

Pacing and attribution

One request at a time, two seconds apart, widening when the site pushes back and

narrowing again on a run of clean answers. The floor of 1.5 seconds cannot be

lowered. The agent string carries the project name, its version and the address

of this repository, so the site can reach a person.

Subtitles are the work of the people who wrote and timed them. This server reads

the catalogue and downloads no subtitle file: every record carries `page_url`,

which is the page a reader opens to download it. Credit tvsubtitles.net and link

that page when you show a result.

This MCP server is not affiliated with tvsubtitles.net.

Privacy

No account, no key, no telemetry. The only host reached is

`https://www.tvsubtitles.net`. Pages are held in memory for fifteen minutes and

nothing is written to disk. Diagnostics go to stderr. See PRIVACY.md.

Development

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

`npm run test:live` makes one request per route against the site, and runs

nightly.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md

and SECURITY.md.

License

MIT, see LICENSE.

mcp-tvsubtitles (français)

_English version_

TVsubtitles.net catalogue les sous-titres de

séries télévisées. Ses lecteurs y déposent un fichier pour un épisode, calé sur

une version vidéo, et le site enregistre la langue, la version pour laquelle il a

été taillé, qui l'a déposé et quand, la taille du fichier et le nombre de fois

qu'il a été pris. Il en tient environ trois cent mille, sur quelque quatre-vingt-six

mille épisodes, dans vingt-quatre langues.

Ce serveur relie un client de conversation à ce catalogue. On peut chercher une

série, lire une saison en voyant quelles langues tiennent quelque chose pour

chaque épisode, lire les fiches d'un épisode, et ouvrir une fiche avec la version

pour laquelle elle a été taillée et qui l'a déposée. Chaque fiche porte l'adresse

de sa page sur le site. Aucune clé d'API ni aucun compte ne sont nécessaires.

Installation

Installation en un clic

Claude Code

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

Tout client lisant `mcpServers`

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

Avec Docker

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

Le conteneur joint `https://www.tvsubtitles.net` et rien d'autre.

Bundle, sans npm

Télécharger `mcp-tvsubtitles.mcpb` depuis la

dernière publication

et l'ouvrir avec un hôte qui installe les bundles MCP. Il emporte ses

dépendances, donc Node 24 ou plus récent suffit.

Ce qu'on peut demander

• « Est-ce que tvsubtitles a des sous-titres français pour Smallville ? »
• « Quelles langues couvrent la saison 3 de Harbour Lights ? »
• « Liste les sous-titres anglais de l'épisode 7 de cette saison. »
• « Sur quelle version ce sous-titre est-il calé, et qui l'a déposé ? »
• « Trouve-moi la page pour télécharger le sous-titre polonais du dernier épisode. »

Les outils

`search_titles`

Cherche dans le catalogue par le nom. Le site ne catalogue que la télévision,

donc une recherche de film est refusée au lieu d'être répondue.

En retour : les séries trouvées, chacune avec l'`id` que prennent les autres

outils, les années publiées par le site et les langues pour lesquelles il dessine

un drapeau. `imdb_id` et `tmdb_id` valent null, puisque la recherche du site n'en

publie aucun. `subtitle_count`, `episode_count` et `season_count` valent null

tant que `with_counts` ne les demande pas, car le site publie ces trois chiffres

sur l'index de son catalogue et non sur la page qui répond à une recherche ;

chacun compte toutes les saisons de la série ensemble, ce que `counts_scope`

nomme, chacun se lit à part, et une série dont l'index ne porte aucune ligne

garde trois null. `total_available` compte les lignes que cette recherche a

ramenées, ce que `total_counts` nomme. Une année qui ne laisse rien est mise de

côté et nommée dans `filters_dropped`.

`list_subtitles`

Lit ce qu'une série tient, sous l'une de deux formes que `kind` nomme.

En retour : avec une saison seule, `kind` vaut `coverage` et chaque ligne est

un épisode, portant `episode_id`, le nombre de sous-titres que le site compte et

les langues qui tiennent quelque chose. Avec un épisode nommé, `kind` vaut

`subtitles` et chaque ligne est une fiche portant l'`id` que prend

`get_subtitle`. `season` est la saison servie par le site et `season_requested`

celle demandée, les deux différant quand la plus récente a été lue.

`seasons_available` liste les saisons que la série tient. Une langue qui ne tient

rien est mise de côté, la réponse revient sans la restriction, et

`filters_dropped` la nomme.

`get_subtitle`

Lit une fiche depuis un id rendu par `list_subtitles`.

En retour : la fiche, avec `page_url` pour la page qu'un lecteur ouvre afin

de télécharger le fichier. `read_from` vaut ici `record`, et `listing` sur une

ligne venue de `list_subtitles` : c'est ce qui distingue un champ non lu d'un

champ que le site ne publie pas, car une liste ne porte ni `file_name`, ni

`size_text`, ni `comment`, que le site n'imprime que sur la page d'une fiche. `releases` porte les versions vidéo publiées par le

site et `release_match` dit s'il en a publié une : `stated` quand oui, `none`

quand non, donc une fiche marquée `none` ne dit rien de la vidéo sur laquelle

elle est calée. `uploader` vaut null sur environ deux fiches sur trois.

`published_at` est l'horodatage du site lu en ISO 8601 et ne porte aucun fuseau,

et `published_text` garde la formulation du site. `rating` porte deux compteurs

que le site publie, où un zéro est un chiffre qu'il a imprimé.

`list_languages`

Liste les langues que le site catalogue, ou celles que tient une série.

En retour : chaque langue avec le nom que le site imprime, le `site_code` de

deux lettres par lequel il l'adresse, le `code` BCP 47 quand la correspondance

est certaine, et `differs_from_iso`. `scope` dit ce qui a été mesuré :

`catalogue` pour le site entier, ou `season` quand un id de série a été passé, et

`count` vaut alors les épisodes de cette saison qui tiennent la langue.

Les langues, et les codes du site

Le site dessine vingt-quatre drapeaux et adresse chaque langue par deux lettres

de son choix. Six diffèrent de l'ISO 639-1, et l'une entre en collision : le site

écrit `br` pour le portugais brésilien, que l'ISO attribue au breton.

`language` garde le nom du site et `language_code` porte le tag, donc rien n'est

à déduire des deux lettres. `list_subtitles` accepte une langue écrite de l'une

des trois façons.

Configuration

Rien n'est à régler. Toutes les variables ci-dessous sont optionnelles.

Une valeur hors bornes est refusée sur stderr et le défaut s'applique.

Erreurs

Comme bibliothèque

La couche qui lit le site est publiée seule, avec son rythme, son cache et ses

codes d'erreur, sans protocole attaché.

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);

Toute lecture rend `{ data, cached }`, avec `skipped` quand des lignes ont été

écartées. Le constructeur prend `{ config, logger, fetchImpl }`, et le plancher

d'intervalle tient quoi qu'on lui passe.

Rythme et attribution

Une requête à la fois, deux secondes d'écart, élargi quand le site repousse et

resserré après une série de réponses propres. Le plancher d'une seconde et demie

ne peut pas être abaissé. La chaîne d'agent porte le nom du projet, sa version et

l'adresse de ce dépôt, pour que le site puisse joindre une personne.

Les sous-titres sont l'œuvre de ceux qui les ont écrits et calés. Ce serveur lit

le catalogue et ne télécharge aucun fichier de sous-titres : chaque fiche porte

`page_url`, la page qu'un lecteur ouvre pour le télécharger. Créditer

tvsubtitles.net et lier cette page en montrant un résultat.

Ce serveur MCP n'est pas affilié à tvsubtitles.net.

Confidentialité

Aucun compte, aucune clé, aucune télémétrie. Le seul hôte joint est

`https://www.tvsubtitles.net`. Les pages sont gardées quinze minutes en mémoire

et rien n'est écrit sur le disque. Les diagnostics vont sur stderr. Voir

PRIVACY.md.

Développement

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

`npm run test:live` fait une requête par route contre le site, et tourne chaque

nuit.

Contribuer

Les issues et les pull requests sont bienvenues. Voir

CONTRIBUTING.md et SECURITY.md.

Licence

MIT, voir LICENSE.